blob: 51802cbb266a208d70989c4f0ab3317a76edc1ea [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
Kővágó, Zoltánf0b3d812019-03-08 23:34:14 +0100419HXCOMM Deprecated by -audiodev
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100420DEF("audio-help", 0, QEMU_OPTION_audio_help,
Kővágó, Zoltánf0b3d812019-03-08 23:34:14 +0100421 "-audio-help show -audiodev equivalent of the currently specified audio settings\n",
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100422 QEMU_ARCH_ALL)
423STEXI
424@item -audio-help
425@findex -audio-help
Kővágó, Zoltánf0b3d812019-03-08 23:34:14 +0100426Will show the -audiodev equivalent of the currently specified
427(deprecated) environment variables.
428ETEXI
429
430DEF("audiodev", HAS_ARG, QEMU_OPTION_audiodev,
431 "-audiodev [driver=]driver,id=id[,prop[=value][,...]]\n"
432 " specifies the audio backend to use\n"
433 " id= identifier of the backend\n"
434 " timer-period= timer period in microseconds\n"
435 " in|out.fixed-settings= use fixed settings for host audio\n"
436 " in|out.frequency= frequency to use with fixed settings\n"
437 " in|out.channels= number of channels to use with fixed settings\n"
438 " in|out.format= sample format to use with fixed settings\n"
439 " valid values: s8, s16, s32, u8, u16, u32\n"
440 " in|out.voices= number of voices to use\n"
441 " in|out.buffer-len= length of buffer in microseconds\n"
442 "-audiodev none,id=id,[,prop[=value][,...]]\n"
443 " dummy driver that discards all output\n"
444#ifdef CONFIG_AUDIO_ALSA
445 "-audiodev alsa,id=id[,prop[=value][,...]]\n"
446 " in|out.dev= name of the audio device to use\n"
447 " in|out.period-len= length of period in microseconds\n"
448 " in|out.try-poll= attempt to use poll mode\n"
449 " threshold= threshold (in microseconds) when playback starts\n"
450#endif
451#ifdef CONFIG_AUDIO_COREAUDIO
452 "-audiodev coreaudio,id=id[,prop[=value][,...]]\n"
453 " in|out.buffer-count= number of buffers\n"
454#endif
455#ifdef CONFIG_AUDIO_DSOUND
456 "-audiodev dsound,id=id[,prop[=value][,...]]\n"
457 " latency= add extra latency to playback in microseconds\n"
458#endif
459#ifdef CONFIG_AUDIO_OSS
460 "-audiodev oss,id=id[,prop[=value][,...]]\n"
461 " in|out.dev= path of the audio device to use\n"
462 " in|out.buffer-count= number of buffers\n"
463 " in|out.try-poll= attempt to use poll mode\n"
464 " try-mmap= try using memory mapped access\n"
465 " exclusive= open device in exclusive mode\n"
466 " dsp-policy= set timing policy (0..10), -1 to use fragment mode\n"
467#endif
468#ifdef CONFIG_AUDIO_PA
469 "-audiodev pa,id=id[,prop[=value][,...]]\n"
470 " server= PulseAudio server address\n"
471 " in|out.name= source/sink device name\n"
472#endif
473#ifdef CONFIG_AUDIO_SDL
474 "-audiodev sdl,id=id[,prop[=value][,...]]\n"
475#endif
476#ifdef CONFIG_SPICE
477 "-audiodev spice,id=id[,prop[=value][,...]]\n"
478#endif
479 "-audiodev wav,id=id[,prop[=value][,...]]\n"
480 " path= path of wav file to record\n",
481 QEMU_ARCH_ALL)
482STEXI
483@item -audiodev [driver=]@var{driver},id=@var{id}[,@var{prop}[=@var{value}][,...]]
484@findex -audiodev
485Adds a new audio backend @var{driver} identified by @var{id}. There are
486global and driver specific properties. Some values can be set
487differently for input and output, they're marked with @code{in|out.}.
488You can set the input's property with @code{in.@var{prop}} and the
489output's property with @code{out.@var{prop}}. For example:
490@example
491-audiodev alsa,id=example,in.frequency=44110,out.frequency=8000
492-audiodev alsa,id=example,out.channels=1 # leaves in.channels unspecified
493@end example
494
495Valid global options are:
496
497@table @option
498@item id=@var{identifier}
499Identifies the audio backend.
500
501@item timer-period=@var{period}
502Sets the timer @var{period} used by the audio subsystem in microseconds.
503Default is 10000 (10 ms).
504
505@item in|out.fixed-settings=on|off
506Use fixed settings for host audio. When off, it will change based on
507how the guest opens the sound card. In this case you must not specify
508@var{frequency}, @var{channels} or @var{format}. Default is on.
509
510@item in|out.frequency=@var{frequency}
511Specify the @var{frequency} to use when using @var{fixed-settings}.
512Default is 44100Hz.
513
514@item in|out.channels=@var{channels}
515Specify the number of @var{channels} to use when using
516@var{fixed-settings}. Default is 2 (stereo).
517
518@item in|out.format=@var{format}
519Specify the sample @var{format} to use when using @var{fixed-settings}.
520Valid values are: @code{s8}, @code{s16}, @code{s32}, @code{u8},
521@code{u16}, @code{u32}. Default is @code{s16}.
522
523@item in|out.voices=@var{voices}
524Specify the number of @var{voices} to use. Default is 1.
525
526@item in|out.buffer=@var{usecs}
527Sets the size of the buffer in microseconds.
528
529@end table
530
531@item -audiodev none,id=@var{id}[,@var{prop}[=@var{value}][,...]]
532Creates a dummy backend that discards all outputs. This backend has no
533backend specific properties.
534
535@item -audiodev alsa,id=@var{id}[,@var{prop}[=@var{value}][,...]]
536Creates backend using the ALSA. This backend is only available on
537Linux.
538
539ALSA specific options are:
540
541@table @option
542
543@item in|out.dev=@var{device}
544Specify the ALSA @var{device} to use for input and/or output. Default
545is @code{default}.
546
547@item in|out.period-len=@var{usecs}
548Sets the period length in microseconds.
549
550@item in|out.try-poll=on|off
551Attempt to use poll mode with the device. Default is on.
552
553@item threshold=@var{threshold}
554Threshold (in microseconds) when playback starts. Default is 0.
555
556@end table
557
558@item -audiodev coreaudio,id=@var{id}[,@var{prop}[=@var{value}][,...]]
559Creates a backend using Apple's Core Audio. This backend is only
560available on Mac OS and only supports playback.
561
562Core Audio specific options are:
563
564@table @option
565
566@item in|out.buffer-count=@var{count}
567Sets the @var{count} of the buffers.
568
569@end table
570
571@item -audiodev dsound,id=@var{id}[,@var{prop}[=@var{value}][,...]]
572Creates a backend using Microsoft's DirectSound. This backend is only
573available on Windows and only supports playback.
574
575DirectSound specific options are:
576
577@table @option
578
579@item latency=@var{usecs}
580Add extra @var{usecs} microseconds latency to playback. Default is
58110000 (10 ms).
582
583@end table
584
585@item -audiodev oss,id=@var{id}[,@var{prop}[=@var{value}][,...]]
586Creates a backend using OSS. This backend is available on most
587Unix-like systems.
588
589OSS specific options are:
590
591@table @option
592
593@item in|out.dev=@var{device}
594Specify the file name of the OSS @var{device} to use. Default is
595@code{/dev/dsp}.
596
597@item in|out.buffer-count=@var{count}
598Sets the @var{count} of the buffers.
599
600@item in|out.try-poll=on|of
601Attempt to use poll mode with the device. Default is on.
602
603@item try-mmap=on|off
604Try using memory mapped device access. Default is off.
605
606@item exclusive=on|off
607Open the device in exclusive mode (vmix won't work in this case).
608Default is off.
609
610@item dsp-policy=@var{policy}
611Sets the timing policy (between 0 and 10, where smaller number means
612smaller latency but higher CPU usage). Use -1 to use buffer sizes
613specified by @code{buffer} and @code{buffer-count}. This option is
614ignored if you do not have OSS 4. Default is 5.
615
616@end table
617
618@item -audiodev pa,id=@var{id}[,@var{prop}[=@var{value}][,...]]
619Creates a backend using PulseAudio. This backend is available on most
620systems.
621
622PulseAudio specific options are:
623
624@table @option
625
626@item server=@var{server}
627Sets the PulseAudio @var{server} to connect to.
628
629@item in|out.name=@var{sink}
630Use the specified source/sink for recording/playback.
631
632@end table
633
634@item -audiodev sdl,id=@var{id}[,@var{prop}[=@var{value}][,...]]
635Creates a backend using SDL. This backend is available on most systems,
636but you should use your platform's native backend if possible. This
637backend has no backend specific properties.
638
639@item -audiodev spice,id=@var{id}[,@var{prop}[=@var{value}][,...]]
640Creates a backend that sends audio through SPICE. This backend requires
641@code{-spice} and automatically selected in that case, so usually you
642can ignore this option. This backend has no backend specific
643properties.
644
645@item -audiodev wav,id=@var{id}[,@var{prop}[=@var{value}][,...]]
646Creates a backend that writes audio to a WAV file.
647
648Backend specific options are:
649
650@table @option
651
652@item path=@var{path}
653Write recorded audio into the specified file. Default is
654@code{qemu.wav}.
655
656@end table
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100657ETEXI
658
659DEF("soundhw", HAS_ARG, QEMU_OPTION_soundhw,
660 "-soundhw c1,... enable audio support\n"
661 " and only specified sound cards (comma separated list)\n"
662 " use '-soundhw help' to get the list of supported cards\n"
663 " use '-soundhw all' to enable all of them\n", QEMU_ARCH_ALL)
664STEXI
665@item -soundhw @var{card1}[,@var{card2},...] or -soundhw all
666@findex -soundhw
667Enable audio and selected sound hardware. Use 'help' to print all
668available sound hardware.
669
670@example
671qemu-system-i386 -soundhw sb16,adlib disk.img
672qemu-system-i386 -soundhw es1370 disk.img
673qemu-system-i386 -soundhw ac97 disk.img
674qemu-system-i386 -soundhw hda disk.img
675qemu-system-i386 -soundhw all disk.img
676qemu-system-i386 -soundhw help
677@end example
678
679Note that Linux's i810_audio OSS kernel (for AC97) module might
680require manually specifying clocking.
681
682@example
683modprobe i810_audio clocking=48000
684@end example
685ETEXI
686
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100687DEF("device", HAS_ARG, QEMU_OPTION_device,
688 "-device driver[,prop[=value][,...]]\n"
689 " add device (based on driver)\n"
690 " prop=value,... sets driver properties\n"
691 " use '-device help' to print all possible drivers\n"
692 " use '-device driver,help' to print all possible properties\n",
693 QEMU_ARCH_ALL)
694STEXI
695@item -device @var{driver}[,@var{prop}[=@var{value}][,...]]
696@findex -device
697Add device @var{driver}. @var{prop}=@var{value} sets driver
698properties. Valid properties depend on the driver. To get help on
699possible drivers and properties, use @code{-device help} and
700@code{-device @var{driver},help}.
Corey Minyardf8490452015-12-17 12:50:10 -0600701
702Some drivers are:
CĂ©dric Le Goater540c07d2017-04-05 14:41:32 +0200703@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 -0600704
705Add an IPMI BMC. This is a simulation of a hardware management
706interface processor that normally sits on a system. It provides
707a watchdog and the ability to reset and power control the system.
708You need to connect this to an IPMI interface to make it useful
709
710The IPMI slave address to use for the BMC. The default is 0x20.
711This address is the BMC's address on the I2C network of management
712controllers. If you don't know what this means, it is safe to ignore
713it.
714
CĂ©dric Le Goater8c6fd7f2017-04-05 14:41:31 +0200715@table @option
716@item bmc=@var{id}
717The BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern above.
718@item slave_addr=@var{val}
719Define slave address to use for the BMC. The default is 0x20.
720@item sdrfile=@var{file}
CĂ©dric Le Goater540c07d2017-04-05 14:41:32 +0200721file containing raw Sensor Data Records (SDR) data. The default is none.
722@item fruareasize=@var{val}
723size of a Field Replaceable Unit (FRU) area. The default is 1024.
724@item frudatafile=@var{file}
725file containing raw Field Replaceable Unit (FRU) inventory data. The default is none.
CĂ©dric Le Goater8c6fd7f2017-04-05 14:41:31 +0200726@end table
727
Corey Minyardf8490452015-12-17 12:50:10 -0600728@item -device ipmi-bmc-extern,id=@var{id},chardev=@var{id}[,slave_addr=@var{val}]
729
730Add a connection to an external IPMI BMC simulator. Instead of
731locally emulating the BMC like the above item, instead connect
732to an external entity that provides the IPMI services.
733
734A connection is made to an external BMC simulator. If you do this, it
735is strongly recommended that you use the "reconnect=" chardev option
736to reconnect to the simulator if the connection is lost. Note that if
737this is not used carefully, it can be a security issue, as the
738interface has the ability to send resets, NMIs, and power off the VM.
739It's best if QEMU makes a connection to an external simulator running
740on a secure port on localhost, so neither the simulator nor QEMU is
741exposed to any outside network.
742
743See the "lanserv/README.vm" file in the OpenIPMI library for more
744details on the external interface.
745
746@item -device isa-ipmi-kcs,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}]
747
748Add a KCS IPMI interafce on the ISA bus. This also adds a
749corresponding ACPI and SMBIOS entries, if appropriate.
750
751@table @option
752@item bmc=@var{id}
753The BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern above.
754@item ioport=@var{val}
755Define the I/O address of the interface. The default is 0xca0 for KCS.
756@item irq=@var{val}
757Define the interrupt to use. The default is 5. To disable interrupts,
758set this to 0.
759@end table
760
761@item -device isa-ipmi-bt,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}]
762
763Like the KCS interface, but defines a BT interface. The default port is
7640xe4 and the default interrupt is 5.
765
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100766ETEXI
767
768DEF("name", HAS_ARG, QEMU_OPTION_name,
Dr. David Alan Gilbert8f480de2014-01-30 10:20:31 +0000769 "-name string1[,process=string2][,debug-threads=on|off]\n"
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100770 " set the name of the guest\n"
Roman Bolshakov479a5742018-12-17 23:26:01 +0300771 " string1 sets the window title and string2 the process name\n"
772 " When debug-threads is enabled, individual threads are given a separate name\n"
Dr. David Alan Gilbert8f480de2014-01-30 10:20:31 +0000773 " NOTE: The thread names are for debugging and not a stable API.\n",
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100774 QEMU_ARCH_ALL)
775STEXI
776@item -name @var{name}
777@findex -name
778Sets the @var{name} of the guest.
779This name will be displayed in the SDL window caption.
780The @var{name} will also be used for the VNC server.
781Also optionally set the top visible process name in Linux.
Dr. David Alan Gilbert8f480de2014-01-30 10:20:31 +0000782Naming of individual threads can also be enabled on Linux to aid debugging.
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100783ETEXI
784
785DEF("uuid", HAS_ARG, QEMU_OPTION_uuid,
786 "-uuid %08x-%04x-%04x-%04x-%012x\n"
787 " specify machine UUID\n", QEMU_ARCH_ALL)
788STEXI
789@item -uuid @var{uuid}
790@findex -uuid
791Set system UUID.
792ETEXI
793
794STEXI
795@end table
796ETEXI
797DEFHEADING()
798
Markus Armbrusterde6b4f92017-10-02 16:03:00 +0200799DEFHEADING(Block device options:)
Markus Armbruster10adb8b2013-02-13 19:49:43 +0100800STEXI
801@table @option
802ETEXI
803
blueswir15824d652009-03-28 06:44:27 +0000804DEF("fda", HAS_ARG, QEMU_OPTION_fda,
Blue Swirlad960902010-03-29 19:23:52 +0000805 "-fda/-fdb file use 'file' as floppy disk 0/1 image\n", QEMU_ARCH_ALL)
806DEF("fdb", HAS_ARG, QEMU_OPTION_fdb, "", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000807STEXI
808@item -fda @var{file}
Markus Armbrusterf9cfd652015-06-15 14:35:59 +0200809@itemx -fdb @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +0100810@findex -fda
811@findex -fdb
Markus Armbruster92a539d2015-03-17 17:02:20 +0100812Use @var{file} as floppy disk 0/1 image (@pxref{disk_images}).
blueswir15824d652009-03-28 06:44:27 +0000813ETEXI
814
815DEF("hda", HAS_ARG, QEMU_OPTION_hda,
Blue Swirlad960902010-03-29 19:23:52 +0000816 "-hda/-hdb file use 'file' as IDE hard disk 0/1 image\n", QEMU_ARCH_ALL)
817DEF("hdb", HAS_ARG, QEMU_OPTION_hdb, "", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000818DEF("hdc", HAS_ARG, QEMU_OPTION_hdc,
Blue Swirlad960902010-03-29 19:23:52 +0000819 "-hdc/-hdd file use 'file' as IDE hard disk 2/3 image\n", QEMU_ARCH_ALL)
820DEF("hdd", HAS_ARG, QEMU_OPTION_hdd, "", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000821STEXI
822@item -hda @var{file}
Markus Armbrusterf9cfd652015-06-15 14:35:59 +0200823@itemx -hdb @var{file}
824@itemx -hdc @var{file}
825@itemx -hdd @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +0100826@findex -hda
827@findex -hdb
828@findex -hdc
829@findex -hdd
blueswir15824d652009-03-28 06:44:27 +0000830Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}).
831ETEXI
832
833DEF("cdrom", HAS_ARG, QEMU_OPTION_cdrom,
Blue Swirlad960902010-03-29 19:23:52 +0000834 "-cdrom file use 'file' as IDE cdrom image (cdrom is ide1 master)\n",
835 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +0000836STEXI
837@item -cdrom @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +0100838@findex -cdrom
blueswir15824d652009-03-28 06:44:27 +0000839Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and
840@option{-cdrom} at the same time). You can use the host CD-ROM by
841using @file{/dev/cdrom} as filename (@pxref{host_drives}).
842ETEXI
843
Markus Armbruster42e5f392017-02-28 22:27:07 +0100844DEF("blockdev", HAS_ARG, QEMU_OPTION_blockdev,
845 "-blockdev [driver=]driver[,node-name=N][,discard=ignore|unmap]\n"
846 " [,cache.direct=on|off][,cache.no-flush=on|off]\n"
847 " [,read-only=on|off][,detect-zeroes=on|off|unmap]\n"
848 " [,driver specific parameters...]\n"
849 " configure a block backend\n", QEMU_ARCH_ALL)
Kevin Wolfdfaca462016-09-22 16:53:24 +0200850STEXI
851@item -blockdev @var{option}[,@var{option}[,@var{option}[,...]]]
852@findex -blockdev
853
Kevin Wolf370e8322016-09-22 17:24:38 +0200854Define a new block driver node. Some of the options apply to all block drivers,
855other options are only accepted for a specific block driver. See below for a
856list of generic options and options for the most common block drivers.
857
858Options that expect a reference to another node (e.g. @code{file}) can be
859given in two ways. Either you specify the node name of an already existing node
860(file=@var{node-name}), or you define a new node inline, adding options
861for the referenced node after a dot (file.filename=@var{path},file.aio=native).
862
863A block driver node created with @option{-blockdev} can be used for a guest
864device by specifying its node name for the @code{drive} property in a
865@option{-device} argument that defines a block device.
Kevin Wolfdfaca462016-09-22 16:53:24 +0200866
867@table @option
868@item Valid options for any block driver node:
869
870@table @code
871@item driver
872Specifies the block driver to use for the given node.
873@item node-name
874This defines the name of the block driver node by which it will be referenced
875later. The name must be unique, i.e. it must not match the name of a different
876block driver node, or (if you use @option{-drive} as well) the ID of a drive.
877
878If no node name is specified, it is automatically generated. The generated node
879name is not intended to be predictable and changes between QEMU invocations.
880For the top level, an explicit node name must be specified.
881@item read-only
882Open the node read-only. Guest write attempts will fail.
883@item cache.direct
884The host page cache can be avoided with @option{cache.direct=on}. This will
885attempt to do disk IO directly to the guest's memory. QEMU may still perform an
886internal copy of the data.
887@item cache.no-flush
888In case you don't care about data integrity over host failures, you can use
889@option{cache.no-flush=on}. This option tells QEMU that it never needs to write
890any data to the disk but can instead keep things in cache. If anything goes
891wrong, like your host losing power, the disk storage getting disconnected
892accidentally, etc. your image will most probably be rendered unusable.
893@item discard=@var{discard}
894@var{discard} is one of "ignore" (or "off") or "unmap" (or "on") and controls
895whether @code{discard} (also known as @code{trim} or @code{unmap}) requests are
896ignored or passed to the filesystem. Some machine types may not support
897discard requests.
898@item detect-zeroes=@var{detect-zeroes}
899@var{detect-zeroes} is "off", "on" or "unmap" and enables the automatic
900conversion of plain zero writes by the OS to driver specific optimized
901zero write commands. You may even choose "unmap" if @var{discard} is set
902to "unmap" to allow a zero write to be converted to an @code{unmap} operation.
903@end table
904
Kevin Wolf370e8322016-09-22 17:24:38 +0200905@item Driver-specific options for @code{file}
906
907This is the protocol-level block driver for accessing regular files.
908
909@table @code
910@item filename
911The path to the image file in the local filesystem
912@item aio
913Specifies the AIO backend (threads/native, default: threads)
Fam Zheng1878eaf2017-11-24 16:53:51 +0800914@item locking
915Specifies whether the image file is protected with Linux OFD / POSIX locks. The
916default is to use the Linux Open File Descriptor API if available, otherwise no
917lock is applied. (auto/on/off, default: auto)
Kevin Wolf370e8322016-09-22 17:24:38 +0200918@end table
919Example:
920@example
921-blockdev driver=file,node-name=disk,filename=disk.img
922@end example
923
924@item Driver-specific options for @code{raw}
925
926This is the image format block driver for raw images. It is usually
927stacked on top of a protocol level block driver such as @code{file}.
928
929@table @code
930@item file
931Reference to or definition of the data source block driver node
932(e.g. a @code{file} driver node)
933@end table
934Example 1:
935@example
936-blockdev driver=file,node-name=disk_file,filename=disk.img
937-blockdev driver=raw,node-name=disk,file=disk_file
938@end example
939Example 2:
940@example
941-blockdev driver=raw,node-name=disk,file.driver=file,file.filename=disk.img
942@end example
943
944@item Driver-specific options for @code{qcow2}
945
946This is the image format block driver for qcow2 images. It is usually
947stacked on top of a protocol level block driver such as @code{file}.
948
949@table @code
950@item file
951Reference to or definition of the data source block driver node
952(e.g. a @code{file} driver node)
953
954@item backing
955Reference to or definition of the backing file block device (default is taken
Max Reitz4f7be282018-02-24 16:40:33 +0100956from the image file). It is allowed to pass @code{null} here in order to disable
957the default backing file.
Kevin Wolf370e8322016-09-22 17:24:38 +0200958
959@item lazy-refcounts
960Whether to enable the lazy refcounts feature (on/off; default is taken from the
961image file)
962
963@item cache-size
964The maximum total size of the L2 table and refcount block caches in bytes
Leonid Bloch40fb2152018-09-26 19:04:39 +0300965(default: the sum of l2-cache-size and refcount-cache-size)
Kevin Wolf370e8322016-09-22 17:24:38 +0200966
967@item l2-cache-size
968The maximum size of the L2 table cache in bytes
Leonid Bloch80668d02018-09-26 19:04:44 +0300969(default: if cache-size is not specified - 32M on Linux platforms, and 8M on
970non-Linux platforms; otherwise, as large as possible within the cache-size,
971while permitting the requested or the minimal refcount cache size)
Kevin Wolf370e8322016-09-22 17:24:38 +0200972
973@item refcount-cache-size
974The maximum size of the refcount block cache in bytes
Leonid Bloch40fb2152018-09-26 19:04:39 +0300975(default: 4 times the cluster size; or if cache-size is specified, the part of
976it which is not used for the L2 cache)
Kevin Wolf370e8322016-09-22 17:24:38 +0200977
978@item cache-clean-interval
979Clean unused entries in the L2 and refcount caches. The interval is in seconds.
Leonid Bloche3a7b452018-09-29 12:54:54 +0300980The default value is 600 on supporting platforms, and 0 on other platforms.
981Setting it to 0 disables this feature.
Kevin Wolf370e8322016-09-22 17:24:38 +0200982
983@item pass-discard-request
984Whether discard requests to the qcow2 device should be forwarded to the data
985source (on/off; default: on if discard=unmap is specified, off otherwise)
986
987@item pass-discard-snapshot
988Whether discard requests for the data source should be issued when a snapshot
989operation (e.g. deleting a snapshot) frees clusters in the qcow2 file (on/off;
990default: on)
991
992@item pass-discard-other
993Whether discard requests for the data source should be issued on other
994occasions where a cluster gets freed (on/off; default: off)
995
996@item overlap-check
997Which overlap checks to perform for writes to the image
998(none/constant/cached/all; default: cached). For details or finer
999granularity control refer to the QAPI documentation of @code{blockdev-add}.
1000@end table
1001
1002Example 1:
1003@example
1004-blockdev driver=file,node-name=my_file,filename=/tmp/disk.qcow2
1005-blockdev driver=qcow2,node-name=hda,file=my_file,overlap-check=none,cache-size=16777216
1006@end example
1007Example 2:
1008@example
1009-blockdev driver=qcow2,node-name=disk,file.driver=http,file.filename=http://example.com/image.qcow2
1010@end example
1011
1012@item Driver-specific options for other drivers
1013Please refer to the QAPI documentation of the @code{blockdev-add} QMP command.
1014
Kevin Wolfdfaca462016-09-22 16:53:24 +02001015@end table
1016
1017ETEXI
Markus Armbruster42e5f392017-02-28 22:27:07 +01001018
blueswir15824d652009-03-28 06:44:27 +00001019DEF("drive", HAS_ARG, QEMU_OPTION_drive,
1020 "-drive [file=file][,if=type][,bus=n][,unit=m][,media=d][,index=i]\n"
Stefan Hajnoczi92196b22011-08-04 12:26:52 +01001021 " [,cache=writethrough|writeback|none|directsync|unsafe][,format=f]\n"
Kevin Wolf572023f2018-06-13 11:01:30 +02001022 " [,snapshot=on|off][,rerror=ignore|stop|report]\n"
Stefan Hajnoczid1db7602014-04-23 13:55:37 +02001023 " [,werror=ignore|stop|report|enospc][,id=name][,aio=threads|native]\n"
Stefan Hajnoczifb0490f2011-11-17 13:40:32 +00001024 " [,readonly=on|off][,copy-on-read=on|off]\n"
Peter Lieven2f7133b2014-07-28 21:53:02 +02001025 " [,discard=ignore|unmap][,detect-zeroes=on|off|unmap]\n"
Benoît Canet3e9fab62013-09-02 14:14:40 +02001026 " [[,bps=b]|[[,bps_rd=r][,bps_wr=w]]]\n"
1027 " [[,iops=i]|[[,iops_rd=r][,iops_wr=w]]]\n"
1028 " [[,bps_max=bm]|[[,bps_rd_max=rm][,bps_wr_max=wm]]]\n"
1029 " [[,iops_max=im]|[[,iops_rd_max=irm][,iops_wr_max=iwm]]]\n"
Benoît Canet2024c1d2013-09-02 14:14:41 +02001030 " [[,iops_size=is]]\n"
Alberto Garcia76f4afb2015-06-08 18:17:44 +02001031 " [[,group=g]]\n"
Blue Swirlad960902010-03-29 19:23:52 +00001032 " use 'file' as a drive image\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001033STEXI
1034@item -drive @var{option}[,@var{option}[,@var{option}[,...]]]
Stefan Weil6616b2a2010-02-05 23:52:05 +01001035@findex -drive
blueswir15824d652009-03-28 06:44:27 +00001036
Kevin Wolfdfaca462016-09-22 16:53:24 +02001037Define a new drive. This includes creating a block driver node (the backend) as
1038well as a guest device, and is mostly a shortcut for defining the corresponding
1039@option{-blockdev} and @option{-device} options.
1040
1041@option{-drive} accepts all options that are accepted by @option{-blockdev}. In
1042addition, it knows the following options:
blueswir15824d652009-03-28 06:44:27 +00001043
Kevin Wolfb3f046c2009-10-09 10:58:35 +02001044@table @option
blueswir15824d652009-03-28 06:44:27 +00001045@item file=@var{file}
1046This option defines which disk image (@pxref{disk_images}) to use with
1047this drive. If the filename contains comma, you must double it
1048(for instance, "file=my,,file" to use file "my,file").
Ronnie Sahlberg0f5314a2011-10-26 23:51:37 +11001049
1050Special files such as iSCSI devices can be specified using protocol
1051specific URLs. See the section for "Device URL Syntax" for more information.
blueswir15824d652009-03-28 06:44:27 +00001052@item if=@var{interface}
1053This option defines on which type on interface the drive is connected.
Craig Jellicked1fcd02017-03-17 08:49:55 -07001054Available types are: ide, scsi, sd, mtd, floppy, pflash, virtio, none.
blueswir15824d652009-03-28 06:44:27 +00001055@item bus=@var{bus},unit=@var{unit}
1056These options define where is connected the drive by defining the bus number and
1057the unit id.
1058@item index=@var{index}
1059This option defines where is connected the drive by using an index in the list
1060of available connectors of a given interface type.
1061@item media=@var{media}
1062This option defines the type of the media: disk or cdrom.
blueswir15824d652009-03-28 06:44:27 +00001063@item snapshot=@var{snapshot}
Michael Tokarev9d85d552014-04-07 13:34:58 +04001064@var{snapshot} is "on" or "off" and controls snapshot mode for the given drive
1065(see @option{-snapshot}).
blueswir15824d652009-03-28 06:44:27 +00001066@item cache=@var{cache}
Kevin Wolfdfaca462016-09-22 16:53:24 +02001067@var{cache} is "none", "writeback", "unsafe", "directsync" or "writethrough"
1068and controls how the host cache is used to access block data. This is a
1069shortcut that sets the @option{cache.direct} and @option{cache.no-flush}
1070options (as in @option{-blockdev}), and additionally @option{cache.writeback},
1071which provides a default for the @option{write-cache} option of block guest
1072devices (as in @option{-device}). The modes correspond to the following
1073settings:
1074
1075@c Our texi2pod.pl script doesn't support @multitable, so fall back to using
1076@c plain ASCII art (well, UTF-8 art really). This looks okay both in the manpage
1077@c and the HTML output.
1078@example
1079@ │ cache.writeback cache.direct cache.no-flush
1080─────────────┼─────────────────────────────────────────────────
1081writeback │ on off off
1082none │ on on off
1083writethrough │ off off off
1084directsync │ off on off
1085unsafe │ on off on
1086@end example
1087
1088The default mode is @option{cache=writeback}.
1089
Christoph Hellwig5c6c3a62009-08-20 16:58:35 +02001090@item aio=@var{aio}
1091@var{aio} is "threads", or "native" and selects between pthread based disk I/O and native Linux AIO.
blueswir15824d652009-03-28 06:44:27 +00001092@item format=@var{format}
1093Specify which disk @var{format} will be used rather than detecting
Michael Tokarevd33c8a72016-05-18 15:47:53 +03001094the format. Can be used to specify format=raw to avoid interpreting
blueswir15824d652009-03-28 06:44:27 +00001095an untrusted format header.
Luiz Capitulinoae73e592011-07-12 17:35:08 -03001096@item werror=@var{action},rerror=@var{action}
1097Specify which @var{action} to take on write and read errors. Valid actions are:
1098"ignore" (ignore the error and try to continue), "stop" (pause QEMU),
1099"report" (report the error to the guest), "enospc" (pause QEMU only if the
1100host disk is full; report the error to the guest otherwise).
1101The default setting is @option{werror=enospc} and @option{rerror=report}.
Stefan Hajnoczifb0490f2011-11-17 13:40:32 +00001102@item copy-on-read=@var{copy-on-read}
1103@var{copy-on-read} is "on" or "off" and enables whether to copy read backing
1104file sectors into the image file.
Stefan Hajnoczi01f9cfa2017-03-01 11:50:24 +00001105@item bps=@var{b},bps_rd=@var{r},bps_wr=@var{w}
1106Specify bandwidth throttling limits in bytes per second, either for all request
1107types or for reads or writes only. Small values can lead to timeouts or hangs
1108inside the guest. A safe minimum for disks is 2 MB/s.
1109@item bps_max=@var{bm},bps_rd_max=@var{rm},bps_wr_max=@var{wm}
1110Specify bursts in bytes per second, either for all request types or for reads
1111or writes only. Bursts allow the guest I/O to spike above the limit
1112temporarily.
1113@item iops=@var{i},iops_rd=@var{r},iops_wr=@var{w}
1114Specify request rate limits in requests per second, either for all request
1115types or for reads or writes only.
1116@item iops_max=@var{bm},iops_rd_max=@var{rm},iops_wr_max=@var{wm}
1117Specify bursts in requests per second, either for all request types or for reads
1118or writes only. Bursts allow the guest I/O to spike above the limit
1119temporarily.
1120@item iops_size=@var{is}
1121Let every @var{is} bytes of a request count as a new request for iops
1122throttling purposes. Use this option to prevent guests from circumventing iops
1123limits by sending fewer but larger requests.
1124@item group=@var{g}
1125Join a throttling quota group with given name @var{g}. All drives that are
1126members of the same group are accounted for together. Use this option to
1127prevent guests from circumventing throttling limits by using many small disks
1128instead of a single larger disk.
blueswir15824d652009-03-28 06:44:27 +00001129@end table
1130
Kevin Wolfdfaca462016-09-22 16:53:24 +02001131By default, the @option{cache.writeback=on} mode is used. It will report data
Kevin Wolfa13e5e02012-11-21 12:26:56 +01001132writes as completed as soon as the data is present in the host page cache.
1133This is safe as long as your guest OS makes sure to correctly flush disk caches
1134where needed. If your guest OS does not handle volatile disk write caches
1135correctly and your host crashes or loses power, then the guest may experience
1136data corruption.
blueswir15824d652009-03-28 06:44:27 +00001137
Kevin Wolfdfaca462016-09-22 16:53:24 +02001138For such guests, you should consider using @option{cache.writeback=off}. This
Kevin Wolfa13e5e02012-11-21 12:26:56 +01001139means that the host page cache will be used to read and write data, but write
1140notification will be sent to the guest only after QEMU has made sure to flush
1141each write to the disk. Be aware that this has a major impact on performance.
blueswir15824d652009-03-28 06:44:27 +00001142
Kevin Wolfdfaca462016-09-22 16:53:24 +02001143When using the @option{-snapshot} option, unsafe caching is always used.
Alexander Graf016f5cf2010-05-26 17:51:49 +02001144
Stefan Hajnoczifb0490f2011-11-17 13:40:32 +00001145Copy-on-read avoids accessing the same backing file sectors repeatedly and is
1146useful when the backing file is over a slow network. By default copy-on-read
1147is off.
1148
blueswir15824d652009-03-28 06:44:27 +00001149Instead of @option{-cdrom} you can use:
1150@example
Stefan Weil3804da92012-05-11 22:21:50 +02001151qemu-system-i386 -drive file=file,index=2,media=cdrom
blueswir15824d652009-03-28 06:44:27 +00001152@end example
1153
1154Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can
1155use:
1156@example
Stefan Weil3804da92012-05-11 22:21:50 +02001157qemu-system-i386 -drive file=file,index=0,media=disk
1158qemu-system-i386 -drive file=file,index=1,media=disk
1159qemu-system-i386 -drive file=file,index=2,media=disk
1160qemu-system-i386 -drive file=file,index=3,media=disk
blueswir15824d652009-03-28 06:44:27 +00001161@end example
1162
Corey Bryant587ed6b2012-10-18 15:19:34 -04001163You can open an image using pre-opened file descriptors from an fd set:
1164@example
1165qemu-system-i386
1166-add-fd fd=3,set=2,opaque="rdwr:/path/to/file"
1167-add-fd fd=4,set=2,opaque="rdonly:/path/to/file"
1168-drive file=/dev/fdset/2,index=0,media=disk
1169@end example
1170
blueswir15824d652009-03-28 06:44:27 +00001171You can connect a CDROM to the slave of ide0:
1172@example
Stefan Weil3804da92012-05-11 22:21:50 +02001173qemu-system-i386 -drive file=file,if=ide,index=1,media=cdrom
blueswir15824d652009-03-28 06:44:27 +00001174@end example
1175
1176If you don't specify the "file=" argument, you define an empty drive:
1177@example
Stefan Weil3804da92012-05-11 22:21:50 +02001178qemu-system-i386 -drive if=ide,index=1,media=cdrom
blueswir15824d652009-03-28 06:44:27 +00001179@end example
1180
blueswir15824d652009-03-28 06:44:27 +00001181Instead of @option{-fda}, @option{-fdb}, you can use:
1182@example
Stefan Weil3804da92012-05-11 22:21:50 +02001183qemu-system-i386 -drive file=file,index=0,if=floppy
1184qemu-system-i386 -drive file=file,index=1,if=floppy
blueswir15824d652009-03-28 06:44:27 +00001185@end example
1186
1187By default, @var{interface} is "ide" and @var{index} is automatically
1188incremented:
1189@example
Stefan Weil3804da92012-05-11 22:21:50 +02001190qemu-system-i386 -drive file=a -drive file=b"
blueswir15824d652009-03-28 06:44:27 +00001191@end example
1192is interpreted like:
1193@example
Stefan Weil3804da92012-05-11 22:21:50 +02001194qemu-system-i386 -hda a -hdb b
blueswir15824d652009-03-28 06:44:27 +00001195@end example
1196ETEXI
1197
1198DEF("mtdblock", HAS_ARG, QEMU_OPTION_mtdblock,
Blue Swirlad960902010-03-29 19:23:52 +00001199 "-mtdblock file use 'file' as on-board Flash memory image\n",
1200 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001201STEXI
Kevin Wolf4e257e52009-10-09 10:58:36 +02001202@item -mtdblock @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01001203@findex -mtdblock
Kevin Wolf4e257e52009-10-09 10:58:36 +02001204Use @var{file} as on-board Flash memory image.
blueswir15824d652009-03-28 06:44:27 +00001205ETEXI
1206
1207DEF("sd", HAS_ARG, QEMU_OPTION_sd,
Blue Swirlad960902010-03-29 19:23:52 +00001208 "-sd file use 'file' as SecureDigital card image\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001209STEXI
Kevin Wolf4e257e52009-10-09 10:58:36 +02001210@item -sd @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01001211@findex -sd
Kevin Wolf4e257e52009-10-09 10:58:36 +02001212Use @var{file} as SecureDigital card image.
blueswir15824d652009-03-28 06:44:27 +00001213ETEXI
1214
1215DEF("pflash", HAS_ARG, QEMU_OPTION_pflash,
Blue Swirlad960902010-03-29 19:23:52 +00001216 "-pflash file use 'file' as a parallel flash image\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001217STEXI
Kevin Wolf4e257e52009-10-09 10:58:36 +02001218@item -pflash @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01001219@findex -pflash
Kevin Wolf4e257e52009-10-09 10:58:36 +02001220Use @var{file} as a parallel flash image.
blueswir15824d652009-03-28 06:44:27 +00001221ETEXI
1222
blueswir15824d652009-03-28 06:44:27 +00001223DEF("snapshot", 0, QEMU_OPTION_snapshot,
Blue Swirlad960902010-03-29 19:23:52 +00001224 "-snapshot write to temporary files instead of disk image files\n",
1225 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001226STEXI
1227@item -snapshot
Stefan Weil6616b2a2010-02-05 23:52:05 +01001228@findex -snapshot
blueswir15824d652009-03-28 06:44:27 +00001229Write to temporary files instead of disk image files. In this case,
1230the raw disk image you use is not written back. You can however force
1231the write back by pressing @key{C-a s} (@pxref{disk_images}).
1232ETEXI
1233
Gautham R Shenoy74db9202010-04-29 17:44:43 +05301234DEF("fsdev", HAS_ARG, QEMU_OPTION_fsdev,
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +05301235 "-fsdev fsdriver,id=id[,path=path,][security_model={mapped-xattr|mapped-file|passthrough|none}]\n"
Tobias Schrammb96feb22017-06-29 15:11:50 +02001236 " [,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd][,fmode=fmode][,dmode=dmode]\n"
Pradeep Jagadeeshb8bbdb82017-02-28 10:31:46 +01001237 " [[,throttling.bps-total=b]|[[,throttling.bps-read=r][,throttling.bps-write=w]]]\n"
1238 " [[,throttling.iops-total=i]|[[,throttling.iops-read=r][,throttling.iops-write=w]]]\n"
1239 " [[,throttling.bps-total-max=bm]|[[,throttling.bps-read-max=rm][,throttling.bps-write-max=wm]]]\n"
1240 " [[,throttling.iops-total-max=im]|[[,throttling.iops-read-max=irm][,throttling.iops-write-max=iwm]]]\n"
1241 " [[,throttling.iops-size=is]]\n",
Gautham R Shenoy74db9202010-04-29 17:44:43 +05301242 QEMU_ARCH_ALL)
1243
1244STEXI
1245
Tobias Schrammb96feb22017-06-29 15:11:50 +02001246@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 +05301247@findex -fsdev
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301248Define a new file system device. Valid options are:
1249@table @option
1250@item @var{fsdriver}
1251This option specifies the fs driver backend to use.
Greg Kurz93aee842018-12-12 14:18:10 +01001252Currently "local" and "proxy" file system drivers are supported.
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301253@item id=@var{id}
1254Specifies identifier for this device
1255@item path=@var{path}
1256Specifies the export path for the file system device. Files under
1257this path will be available to the 9p client on the guest.
1258@item security_model=@var{security_model}
1259Specifies the security model to be used for this export path.
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +05301260Supported security models are "passthrough", "mapped-xattr", "mapped-file" and "none".
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301261In "passthrough" security model, files are stored using the same
Stefan Weilb65ee4f2012-05-11 22:25:50 +02001262credentials as they are created on the guest. This requires QEMU
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +05301263to run as root. In "mapped-xattr" security model, some of the file
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301264attributes like uid, gid, mode bits and link target are stored as
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +05301265file attributes. For "mapped-file" these attributes are stored in the
1266hidden .virtfs_metadata directory. Directories exported by this security model cannot
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301267interact with other unix tools. "none" security model is same as
1268passthrough except the sever won't report failures if it fails to
M. Mohan Kumard9b36a62011-10-14 12:59:37 +05301269set file attributes like ownership. Security model is mandatory
Greg Kurz93aee842018-12-12 14:18:10 +01001270only for local fsdriver. Other fsdrivers (like proxy) don't take
M. Mohan Kumard9b36a62011-10-14 12:59:37 +05301271security model as a parameter.
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301272@item writeout=@var{writeout}
1273This is an optional argument. The only supported value is "immediate".
1274This means that host page cache will be used to read and write data but
1275write notification will be sent to the guest only when the data has been
1276reported as written by the storage subsystem.
M. Mohan Kumar2c74c2c2011-10-25 12:10:39 +05301277@item readonly
1278Enables exporting 9p share as a readonly mount for guests. By default
1279read-write access is given.
M. Mohan Kumar84a87cc2011-12-14 13:58:47 +05301280@item socket=@var{socket}
1281Enables proxy filesystem driver to use passed socket file for communicating
1282with virtfs-proxy-helper
M. Mohan Kumarf67e3ff2011-12-14 13:58:46 +05301283@item sock_fd=@var{sock_fd}
1284Enables proxy filesystem driver to use passed socket descriptor for
1285communicating with virtfs-proxy-helper. Usually a helper like libvirt
1286will create socketpair and pass one of the fds as sock_fd
Tobias Schrammb96feb22017-06-29 15:11:50 +02001287@item fmode=@var{fmode}
1288Specifies the default mode for newly created files on the host. Works only
1289with security models "mapped-xattr" and "mapped-file".
1290@item dmode=@var{dmode}
1291Specifies the default mode for newly created directories on the host. Works
1292only with security models "mapped-xattr" and "mapped-file".
Gautham R Shenoy74db9202010-04-29 17:44:43 +05301293@end table
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301294
1295-fsdev option is used along with -device driver "virtio-9p-pci".
1296@item -device virtio-9p-pci,fsdev=@var{id},mount_tag=@var{mount_tag}
1297Options for virtio-9p-pci driver are:
1298@table @option
1299@item fsdev=@var{id}
1300Specifies the id value specified along with -fsdev option
1301@item mount_tag=@var{mount_tag}
1302Specifies the tag name to be used by the guest to mount this export point
1303@end table
1304
Gautham R Shenoy74db9202010-04-29 17:44:43 +05301305ETEXI
Gautham R Shenoy74db9202010-04-29 17:44:43 +05301306
Gautham R Shenoy3d54abc2010-04-29 17:45:03 +05301307DEF("virtfs", HAS_ARG, QEMU_OPTION_virtfs,
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +05301308 "-virtfs local,path=path,mount_tag=tag,security_model=[mapped-xattr|mapped-file|passthrough|none]\n"
Tobias Schrammb96feb22017-06-29 15:11:50 +02001309 " [,id=id][,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd][,fmode=fmode][,dmode=dmode]\n",
Gautham R Shenoy3d54abc2010-04-29 17:45:03 +05301310 QEMU_ARCH_ALL)
1311
1312STEXI
1313
Tobias Schrammb96feb22017-06-29 15:11:50 +02001314@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 +05301315@findex -virtfs
Gautham R Shenoy3d54abc2010-04-29 17:45:03 +05301316
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301317The general form of a Virtual File system pass-through options are:
1318@table @option
1319@item @var{fsdriver}
1320This option specifies the fs driver backend to use.
Greg Kurz93aee842018-12-12 14:18:10 +01001321Currently "local" and "proxy" file system drivers are supported.
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301322@item id=@var{id}
1323Specifies identifier for this device
1324@item path=@var{path}
1325Specifies the export path for the file system device. Files under
1326this path will be available to the 9p client on the guest.
1327@item security_model=@var{security_model}
1328Specifies the security model to be used for this export path.
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +05301329Supported security models are "passthrough", "mapped-xattr", "mapped-file" and "none".
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301330In "passthrough" security model, files are stored using the same
Stefan Weilb65ee4f2012-05-11 22:25:50 +02001331credentials as they are created on the guest. This requires QEMU
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +05301332to run as root. In "mapped-xattr" security model, some of the file
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301333attributes like uid, gid, mode bits and link target are stored as
Aneesh Kumar K.V2c30dd72012-01-19 12:21:11 +05301334file attributes. For "mapped-file" these attributes are stored in the
1335hidden .virtfs_metadata directory. Directories exported by this security model cannot
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301336interact with other unix tools. "none" security model is same as
1337passthrough except the sever won't report failures if it fails to
M. Mohan Kumard9b36a62011-10-14 12:59:37 +05301338set file attributes like ownership. Security model is mandatory only
Greg Kurz93aee842018-12-12 14:18:10 +01001339for local fsdriver. Other fsdrivers (like proxy) don't take security
M. Mohan Kumard9b36a62011-10-14 12:59:37 +05301340model as a parameter.
Aneesh Kumar K.V7c92a3d2011-10-12 19:11:24 +05301341@item writeout=@var{writeout}
1342This is an optional argument. The only supported value is "immediate".
1343This means that host page cache will be used to read and write data but
1344write notification will be sent to the guest only when the data has been
1345reported as written by the storage subsystem.
M. Mohan Kumar2c74c2c2011-10-25 12:10:39 +05301346@item readonly
1347Enables exporting 9p share as a readonly mount for guests. By default
1348read-write access is given.
M. Mohan Kumar84a87cc2011-12-14 13:58:47 +05301349@item socket=@var{socket}
1350Enables proxy filesystem driver to use passed socket file for
1351communicating with virtfs-proxy-helper. Usually a helper like libvirt
1352will create socketpair and pass one of the fds as sock_fd
M. Mohan Kumarf67e3ff2011-12-14 13:58:46 +05301353@item sock_fd
1354Enables proxy filesystem driver to use passed 'sock_fd' as the socket
1355descriptor for interfacing with virtfs-proxy-helper
Tobias Schrammb96feb22017-06-29 15:11:50 +02001356@item fmode=@var{fmode}
1357Specifies the default mode for newly created files on the host. Works only
1358with security models "mapped-xattr" and "mapped-file".
1359@item dmode=@var{dmode}
1360Specifies the default mode for newly created directories on the host. Works
1361only with security models "mapped-xattr" and "mapped-file".
Gautham R Shenoy3d54abc2010-04-29 17:45:03 +05301362@end table
1363ETEXI
Gautham R Shenoy3d54abc2010-04-29 17:45:03 +05301364
Aneesh Kumar K.V9db221a2011-10-25 12:10:40 +05301365DEF("virtfs_synth", 0, QEMU_OPTION_virtfs_synth,
1366 "-virtfs_synth Create synthetic file system image\n",
1367 QEMU_ARCH_ALL)
1368STEXI
1369@item -virtfs_synth
1370@findex -virtfs_synth
1371Create synthetic file system image
1372ETEXI
1373
Markus Armbruster61d70482017-10-02 16:03:03 +02001374DEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi,
1375 "-iscsi [user=user][,password=password]\n"
1376 " [,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE\n"
1377 " [,initiator-name=initiator-iqn][,id=target-iqn]\n"
1378 " [,timeout=timeout]\n"
1379 " iSCSI session parameters\n", QEMU_ARCH_ALL)
1380
blueswir15824d652009-03-28 06:44:27 +00001381STEXI
Markus Armbruster44743142017-10-02 16:03:04 +02001382@item -iscsi
1383@findex -iscsi
1384Configure iSCSI session parameters.
1385ETEXI
1386
1387STEXI
blueswir15824d652009-03-28 06:44:27 +00001388@end table
1389ETEXI
blueswir15824d652009-03-28 06:44:27 +00001390DEFHEADING()
1391
Markus Armbrusterde6b4f92017-10-02 16:03:00 +02001392DEFHEADING(USB options:)
Markus Armbruster10adb8b2013-02-13 19:49:43 +01001393STEXI
1394@table @option
1395ETEXI
1396
1397DEF("usb", 0, QEMU_OPTION_usb,
Thomas Hutha358a3a2017-05-19 08:35:16 +02001398 "-usb enable the USB driver (if it is not used by default yet)\n",
Markus Armbruster10adb8b2013-02-13 19:49:43 +01001399 QEMU_ARCH_ALL)
1400STEXI
1401@item -usb
1402@findex -usb
Thomas Hutha358a3a2017-05-19 08:35:16 +02001403Enable the USB driver (if it is not used by default yet).
Markus Armbruster10adb8b2013-02-13 19:49:43 +01001404ETEXI
1405
1406DEF("usbdevice", HAS_ARG, QEMU_OPTION_usbdevice,
1407 "-usbdevice name add the host or guest USB device 'name'\n",
1408 QEMU_ARCH_ALL)
1409STEXI
1410
1411@item -usbdevice @var{devname}
1412@findex -usbdevice
Thomas Hutha358a3a2017-05-19 08:35:16 +02001413Add the USB device @var{devname}. Note that this option is deprecated,
1414please use @code{-device usb-...} instead. @xref{usb_devices}.
Markus Armbruster10adb8b2013-02-13 19:49:43 +01001415
1416@table @option
1417
1418@item mouse
1419Virtual Mouse. This will override the PS/2 mouse emulation when activated.
1420
1421@item tablet
1422Pointer device that uses absolute coordinates (like a touchscreen). This
1423means QEMU is able to report the mouse position without having to grab the
1424mouse. Also overrides the PS/2 mouse emulation when activated.
1425
Markus Armbruster10adb8b2013-02-13 19:49:43 +01001426@item braille
1427Braille device. This will use BrlAPI to display the braille output on a real
1428or fake device.
1429
Markus Armbruster10adb8b2013-02-13 19:49:43 +01001430@end table
1431ETEXI
1432
1433STEXI
1434@end table
1435ETEXI
1436DEFHEADING()
1437
Markus Armbrusterde6b4f92017-10-02 16:03:00 +02001438DEFHEADING(Display options:)
blueswir15824d652009-03-28 06:44:27 +00001439STEXI
1440@table @option
1441ETEXI
1442
Jes Sorensen1472a952011-03-16 13:33:31 +01001443DEF("display", HAS_ARG, QEMU_OPTION_display,
Marc-André Lureaud8aec9d2019-02-21 12:07:03 +01001444 "-display spice-app[,gl=on|off]\n"
Jes Sorensen1472a952011-03-16 13:33:31 +01001445 "-display sdl[,frame=on|off][,alt_grab=on|off][,ctrl_grab=on|off]\n"
Elie Tournier4867e472018-04-13 14:58:42 +01001446 " [,window_close=on|off][,gl=on|core|es|off]\n"
Robert Hof04ec5a2016-07-26 18:17:11 +08001447 "-display gtk[,grab_on_hover=on|off][,gl=on|off]|\n"
1448 "-display vnc=<display>[,<optargs>]\n"
Samuel Thibault2f8b7cd2019-03-11 14:51:27 +01001449 "-display curses[,charset=<encoding>]\n"
Erik Skultety144aaa92018-11-16 11:14:44 +01001450 "-display none\n"
1451 "-display egl-headless[,rendernode=<file>]"
Robert Hof04ec5a2016-07-26 18:17:11 +08001452 " select display type\n"
1453 "The default display is equivalent to\n"
1454#if defined(CONFIG_GTK)
1455 "\t\"-display gtk\"\n"
1456#elif defined(CONFIG_SDL)
1457 "\t\"-display sdl\"\n"
1458#elif defined(CONFIG_COCOA)
1459 "\t\"-display cocoa\"\n"
1460#elif defined(CONFIG_VNC)
1461 "\t\"-vnc localhost:0,to=99,id=default\"\n"
1462#else
1463 "\t\"-display none\"\n"
1464#endif
1465 , QEMU_ARCH_ALL)
Jes Sorensen1472a952011-03-16 13:33:31 +01001466STEXI
1467@item -display @var{type}
1468@findex -display
1469Select type of display to use. This option is a replacement for the
1470old style -sdl/-curses/... options. Valid values for @var{type} are
1471@table @option
1472@item sdl
1473Display video output via SDL (usually in a separate graphics
1474window; see the SDL documentation for other possibilities).
1475@item curses
1476Display video output via curses. For graphics device models which
1477support a text mode, QEMU can display this output using a
1478curses/ncurses interface. Nothing is displayed when the graphics
1479device is in graphical mode or if the graphics device does not support
1480a text mode. Generally only the VGA device models support text mode.
Samuel Thibault2f8b7cd2019-03-11 14:51:27 +01001481The font charset used by the guest can be specified with the
1482@code{charset} option, for example @code{charset=CP850} for IBM CP850
1483encoding. The default is @code{CP437}.
Jes Sorensen4171d322011-03-16 13:33:32 +01001484@item none
1485Do not display video output. The guest will still see an emulated
1486graphics card, but its output will not be displayed to the QEMU
1487user. This option differs from the -nographic option in that it
1488only affects what is done with video output; -nographic also changes
1489the destination of the serial and parallel port data.
Jan Kiszka881249c2014-03-12 08:33:50 +01001490@item gtk
1491Display video output in a GTK window. This interface provides drop-down
1492menus and other UI elements to configure and control the VM during
1493runtime.
Jes Sorensen3264ff12011-03-16 13:33:33 +01001494@item vnc
1495Start a VNC server on display <arg>
Erik Skultety144aaa92018-11-16 11:14:44 +01001496@item egl-headless
1497Offload all OpenGL operations to a local DRI device. For any graphical display,
1498this display needs to be paired with either VNC or SPICE displays.
Marc-André Lureaud8aec9d2019-02-21 12:07:03 +01001499@item spice-app
1500Start QEMU as a Spice server and launch the default Spice client
1501application. The Spice server will redirect the serial consoles and
1502QEMU monitors. (Since 4.0)
Jes Sorensen1472a952011-03-16 13:33:31 +01001503@end table
1504ETEXI
1505
blueswir15824d652009-03-28 06:44:27 +00001506DEF("nographic", 0, QEMU_OPTION_nographic,
Blue Swirlad960902010-03-29 19:23:52 +00001507 "-nographic disable graphical output and redirect serial I/Os to console\n",
1508 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001509STEXI
1510@item -nographic
Stefan Weil6616b2a2010-02-05 23:52:05 +01001511@findex -nographic
Colin Lorddc0a3e42016-08-12 15:30:48 -04001512Normally, if QEMU is compiled with graphical window support, it displays
1513output such as guest graphics, guest console, and the QEMU monitor in a
1514window. With this option, you can totally disable graphical output so
1515that QEMU is a simple command line application. The emulated serial port
1516is redirected on the console and muxed with the monitor (unless
1517redirected elsewhere explicitly). Therefore, you can still use QEMU to
1518debug a Linux kernel with a serial console. Use @key{C-a h} for help on
1519switching between the console and monitor.
blueswir15824d652009-03-28 06:44:27 +00001520ETEXI
1521
blueswir15824d652009-03-28 06:44:27 +00001522DEF("curses", 0, QEMU_OPTION_curses,
Robert Hof04ec5a2016-07-26 18:17:11 +08001523 "-curses shorthand for -display curses\n",
Blue Swirlad960902010-03-29 19:23:52 +00001524 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001525STEXI
1526@item -curses
Markus Armbrusterb8f490e2013-02-13 19:49:38 +01001527@findex -curses
Colin Lorddc0a3e42016-08-12 15:30:48 -04001528Normally, if QEMU is compiled with graphical window support, it displays
1529output such as guest graphics, guest console, and the QEMU monitor in a
1530window. With this option, QEMU can display the VGA output when in text
1531mode using a curses/ncurses interface. Nothing is displayed in graphical
1532mode.
blueswir15824d652009-03-28 06:44:27 +00001533ETEXI
1534
blueswir15824d652009-03-28 06:44:27 +00001535DEF("alt-grab", 0, QEMU_OPTION_alt_grab,
Blue Swirlad960902010-03-29 19:23:52 +00001536 "-alt-grab use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt)\n",
1537 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001538STEXI
1539@item -alt-grab
Stefan Weil6616b2a2010-02-05 23:52:05 +01001540@findex -alt-grab
Brad Hardsde1db2a2011-04-29 21:46:12 +10001541Use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt). Note that this also
1542affects the special keys (for fullscreen, monitor-mode switching, etc).
blueswir15824d652009-03-28 06:44:27 +00001543ETEXI
1544
Dustin Kirkland0ca9f8a2009-09-17 15:48:04 -05001545DEF("ctrl-grab", 0, QEMU_OPTION_ctrl_grab,
Blue Swirlad960902010-03-29 19:23:52 +00001546 "-ctrl-grab use Right-Ctrl to grab mouse (instead of Ctrl-Alt)\n",
1547 QEMU_ARCH_ALL)
Dustin Kirkland0ca9f8a2009-09-17 15:48:04 -05001548STEXI
1549@item -ctrl-grab
Stefan Weil6616b2a2010-02-05 23:52:05 +01001550@findex -ctrl-grab
Brad Hardsde1db2a2011-04-29 21:46:12 +10001551Use Right-Ctrl to grab mouse (instead of Ctrl-Alt). Note that this also
1552affects the special keys (for fullscreen, monitor-mode switching, etc).
Dustin Kirkland0ca9f8a2009-09-17 15:48:04 -05001553ETEXI
1554
blueswir15824d652009-03-28 06:44:27 +00001555DEF("no-quit", 0, QEMU_OPTION_no_quit,
Blue Swirlad960902010-03-29 19:23:52 +00001556 "-no-quit disable SDL window close capability\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001557STEXI
1558@item -no-quit
Stefan Weil6616b2a2010-02-05 23:52:05 +01001559@findex -no-quit
blueswir15824d652009-03-28 06:44:27 +00001560Disable SDL window close capability.
1561ETEXI
1562
blueswir15824d652009-03-28 06:44:27 +00001563DEF("sdl", 0, QEMU_OPTION_sdl,
Robert Hof04ec5a2016-07-26 18:17:11 +08001564 "-sdl shorthand for -display sdl\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001565STEXI
1566@item -sdl
Stefan Weil6616b2a2010-02-05 23:52:05 +01001567@findex -sdl
blueswir15824d652009-03-28 06:44:27 +00001568Enable SDL.
1569ETEXI
1570
Gerd Hoffmann29b00402010-03-11 11:13:27 -03001571DEF("spice", HAS_ARG, QEMU_OPTION_spice,
Yonit Halperin27af7782012-08-21 13:54:20 +03001572 "-spice [port=port][,tls-port=secured-port][,x509-dir=<dir>]\n"
1573 " [,x509-key-file=<file>][,x509-key-password=<file>]\n"
1574 " [,x509-cert-file=<file>][,x509-cacert-file=<file>]\n"
Marc-André Lureaufe4831b2015-01-13 17:57:51 +01001575 " [,x509-dh-key-file=<file>][,addr=addr][,ipv4|ipv6|unix]\n"
Yonit Halperin27af7782012-08-21 13:54:20 +03001576 " [,tls-ciphers=<list>]\n"
1577 " [,tls-channel=[main|display|cursor|inputs|record|playback]]\n"
1578 " [,plaintext-channel=[main|display|cursor|inputs|record|playback]]\n"
1579 " [,sasl][,password=<secret>][,disable-ticketing]\n"
1580 " [,image-compression=[auto_glz|auto_lz|quic|glz|lz|off]]\n"
1581 " [,jpeg-wan-compression=[auto|never|always]]\n"
1582 " [,zlib-glz-wan-compression=[auto|never|always]]\n"
1583 " [,streaming-video=[off|all|filter]][,disable-copy-paste]\n"
Hans de Goede5ad24e52013-06-08 15:37:27 +02001584 " [,disable-agent-file-xfer][,agent-mouse=[on|off]]\n"
1585 " [,playback-compression=[on|off]][,seamless-migration=[on|off]]\n"
Marc-André Lureau7b525502017-02-12 15:21:18 +04001586 " [,gl=[on|off]][,rendernode=<file>]\n"
Yonit Halperin27af7782012-08-21 13:54:20 +03001587 " enable spice\n"
1588 " at least one of {port, tls-port} is mandatory\n",
1589 QEMU_ARCH_ALL)
Gerd Hoffmann29b00402010-03-11 11:13:27 -03001590STEXI
1591@item -spice @var{option}[,@var{option}[,...]]
1592@findex -spice
1593Enable the spice remote desktop protocol. Valid options are
1594
1595@table @option
1596
1597@item port=<nr>
Gerd Hoffmannc448e852010-03-11 11:13:32 -03001598Set the TCP port spice is listening on for plaintext channels.
Gerd Hoffmann29b00402010-03-11 11:13:27 -03001599
Gerd Hoffmann333b0ee2010-08-27 14:29:16 +02001600@item addr=<addr>
1601Set the IP address spice is listening on. Default is any address.
1602
1603@item ipv4
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02001604@itemx ipv6
1605@itemx unix
Gerd Hoffmann333b0ee2010-08-27 14:29:16 +02001606Force using the specified IP version.
1607
Gerd Hoffmann29b00402010-03-11 11:13:27 -03001608@item password=<secret>
1609Set the password you need to authenticate.
1610
Marc-André Lureau48b3ed02011-05-17 10:40:33 +02001611@item sasl
1612Require that the client use SASL to authenticate with the spice.
1613The exact choice of authentication method used is controlled from the
1614system / user's SASL configuration file for the 'qemu' service. This
1615is typically found in /etc/sasl2/qemu.conf. If running QEMU as an
1616unprivileged user, an environment variable SASL_CONF_PATH can be used
1617to make it search alternate locations for the service config.
1618While some SASL auth methods can also provide data encryption (eg GSSAPI),
1619it is recommended that SASL always be combined with the 'tls' and
1620'x509' settings to enable use of SSL and server certificates. This
1621ensures a data encryption preventing compromise of authentication
1622credentials.
1623
Gerd Hoffmann29b00402010-03-11 11:13:27 -03001624@item disable-ticketing
1625Allow client connects without authentication.
1626
Hans de Goeded4970b02011-03-27 16:43:54 +02001627@item disable-copy-paste
1628Disable copy paste between the client and the guest.
1629
Hans de Goede5ad24e52013-06-08 15:37:27 +02001630@item disable-agent-file-xfer
1631Disable spice-vdagent based file-xfer between the client and the guest.
1632
Gerd Hoffmannc448e852010-03-11 11:13:32 -03001633@item tls-port=<nr>
1634Set the TCP port spice is listening on for encrypted channels.
1635
1636@item x509-dir=<dir>
1637Set the x509 file directory. Expects same filenames as -vnc $display,x509=$dir
1638
1639@item x509-key-file=<file>
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02001640@itemx x509-key-password=<file>
1641@itemx x509-cert-file=<file>
1642@itemx x509-cacert-file=<file>
1643@itemx x509-dh-key-file=<file>
Gerd Hoffmannc448e852010-03-11 11:13:32 -03001644The x509 file names can also be configured individually.
1645
1646@item tls-ciphers=<list>
1647Specify which ciphers to use.
1648
Alon Levyd70d6b32011-12-20 13:05:18 +02001649@item tls-channel=[main|display|cursor|inputs|record|playback]
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02001650@itemx plaintext-channel=[main|display|cursor|inputs|record|playback]
Gerd Hoffmann17b6dea2010-08-27 14:09:56 +02001651Force specific channel to be used with or without TLS encryption. The
1652options can be specified multiple times to configure multiple
1653channels. The special name "default" can be used to set the default
1654mode. For channels which are not explicitly forced into one mode the
1655spice client is allowed to pick tls/plaintext as he pleases.
1656
Yonit Halperin9f04e092010-07-14 13:26:34 +03001657@item image-compression=[auto_glz|auto_lz|quic|glz|lz|off]
1658Configure image compression (lossless).
1659Default is auto_glz.
1660
1661@item jpeg-wan-compression=[auto|never|always]
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02001662@itemx zlib-glz-wan-compression=[auto|never|always]
Yonit Halperin9f04e092010-07-14 13:26:34 +03001663Configure wan image compression (lossy for slow links).
1664Default is auto.
1665
Gerd Hoffmann84a23f22010-08-30 16:36:53 +02001666@item streaming-video=[off|all|filter]
Li Zhijian93ca5192016-08-01 12:06:59 +08001667Configure video stream detection. Default is off.
Gerd Hoffmann84a23f22010-08-30 16:36:53 +02001668
1669@item agent-mouse=[on|off]
1670Enable/disable passing mouse events via vdagent. Default is on.
1671
1672@item playback-compression=[on|off]
1673Enable/disable audio stream compression (using celt 0.5.1). Default is on.
1674
Yonit Halperin8c957052012-08-21 11:51:59 +03001675@item seamless-migration=[on|off]
1676Enable/disable spice seamless migration. Default is off.
1677
Gerd Hoffmann474114b2015-10-13 15:39:34 +02001678@item gl=[on|off]
1679Enable/disable OpenGL context. Default is off.
1680
Marc-André Lureau7b525502017-02-12 15:21:18 +04001681@item rendernode=<file>
1682DRM render node for OpenGL rendering. If not specified, it will pick
1683the first available. (Since 2.9)
1684
Gerd Hoffmann29b00402010-03-11 11:13:27 -03001685@end table
1686ETEXI
1687
blueswir15824d652009-03-28 06:44:27 +00001688DEF("portrait", 0, QEMU_OPTION_portrait,
Blue Swirlad960902010-03-29 19:23:52 +00001689 "-portrait rotate graphical output 90 deg left (only PXA LCD)\n",
1690 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001691STEXI
1692@item -portrait
Stefan Weil6616b2a2010-02-05 23:52:05 +01001693@findex -portrait
blueswir15824d652009-03-28 06:44:27 +00001694Rotate graphical output 90 deg left (only PXA LCD).
1695ETEXI
1696
Vasily Khoruzhick93128052011-06-17 13:04:36 +03001697DEF("rotate", HAS_ARG, QEMU_OPTION_rotate,
1698 "-rotate <deg> rotate graphical output some deg left (only PXA LCD)\n",
1699 QEMU_ARCH_ALL)
1700STEXI
Markus Armbruster6265c432013-02-13 19:49:39 +01001701@item -rotate @var{deg}
Vasily Khoruzhick93128052011-06-17 13:04:36 +03001702@findex -rotate
1703Rotate graphical output some deg left (only PXA LCD).
1704ETEXI
1705
blueswir15824d652009-03-28 06:44:27 +00001706DEF("vga", HAS_ARG, QEMU_OPTION_vga,
Gerd Hoffmanna94f0c52014-09-10 14:28:48 +02001707 "-vga [std|cirrus|vmware|qxl|xenfb|tcx|cg3|virtio|none]\n"
Blue Swirlad960902010-03-29 19:23:52 +00001708 " select video card type\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001709STEXI
malce4558dc2012-08-27 18:33:21 +04001710@item -vga @var{type}
Stefan Weil6616b2a2010-02-05 23:52:05 +01001711@findex -vga
blueswir15824d652009-03-28 06:44:27 +00001712Select type of VGA card to emulate. Valid values for @var{type} are
Kevin Wolfb3f046c2009-10-09 10:58:35 +02001713@table @option
blueswir15824d652009-03-28 06:44:27 +00001714@item cirrus
1715Cirrus Logic GD5446 Video card. All Windows versions starting from
1716Windows 95 should recognize and use this graphic card. For optimal
1717performances, use 16 bit color depth in the guest and the host OS.
Alberto Garcia41eeb0e2017-01-27 11:41:54 +02001718(This card was the default before QEMU 2.2)
blueswir15824d652009-03-28 06:44:27 +00001719@item std
1720Standard VGA card with Bochs VBE extensions. If your guest OS
1721supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if you want
1722to use high resolution modes (>= 1280x1024x16) then you should use
Alberto Garcia41eeb0e2017-01-27 11:41:54 +02001723this option. (This card is the default since QEMU 2.2)
blueswir15824d652009-03-28 06:44:27 +00001724@item vmware
1725VMWare SVGA-II compatible adapter. Use it if you have sufficiently
1726recent XFree86/XOrg server or Windows guest with a driver for this
1727card.
Gerd Hoffmanna19cbfb2010-04-27 11:50:11 +02001728@item qxl
1729QXL paravirtual graphic card. It is VGA compatible (including VESA
17302.0 VBE support). Works best with qxl guest drivers installed though.
1731Recommended choice when using the spice protocol.
Mark Cave-Ayland33632782014-03-17 21:46:25 +00001732@item tcx
1733(sun4m only) Sun TCX framebuffer. This is the default framebuffer for
1734sun4m machines and offers both 8-bit and 24-bit colour depths at a
1735fixed resolution of 1024x768.
1736@item cg3
1737(sun4m only) Sun cgthree framebuffer. This is a simple 8-bit framebuffer
1738for sun4m machines available in both 1024x768 (OpenBIOS) and 1152x900 (OBP)
1739resolutions aimed at people wishing to run older Solaris versions.
Gerd Hoffmanna94f0c52014-09-10 14:28:48 +02001740@item virtio
1741Virtio VGA card.
blueswir15824d652009-03-28 06:44:27 +00001742@item none
1743Disable VGA card.
1744@end table
1745ETEXI
1746
1747DEF("full-screen", 0, QEMU_OPTION_full_screen,
Blue Swirlad960902010-03-29 19:23:52 +00001748 "-full-screen start in full screen\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001749STEXI
1750@item -full-screen
Stefan Weil6616b2a2010-02-05 23:52:05 +01001751@findex -full-screen
blueswir15824d652009-03-28 06:44:27 +00001752Start in full screen.
1753ETEXI
1754
blueswir15824d652009-03-28 06:44:27 +00001755DEF("g", 1, QEMU_OPTION_g ,
Blue Swirlad960902010-03-29 19:23:52 +00001756 "-g WxH[xDEPTH] Set the initial graphical resolution and depth\n",
1757 QEMU_ARCH_PPC | QEMU_ARCH_SPARC)
blueswir15824d652009-03-28 06:44:27 +00001758STEXI
Stefan Weil95d5f082010-01-20 22:25:27 +01001759@item -g @var{width}x@var{height}[x@var{depth}]
Stefan Weil6616b2a2010-02-05 23:52:05 +01001760@findex -g
Stefan Weil95d5f082010-01-20 22:25:27 +01001761Set the initial graphical resolution and depth (PPC, SPARC only).
blueswir15824d652009-03-28 06:44:27 +00001762ETEXI
1763
1764DEF("vnc", HAS_ARG, QEMU_OPTION_vnc ,
Robert Hof04ec5a2016-07-26 18:17:11 +08001765 "-vnc <display> shorthand for -display vnc=<display>\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00001766STEXI
1767@item -vnc @var{display}[,@var{option}[,@var{option}[,...]]]
Stefan Weil6616b2a2010-02-05 23:52:05 +01001768@findex -vnc
Colin Lorddc0a3e42016-08-12 15:30:48 -04001769Normally, if QEMU is compiled with graphical window support, it displays
1770output such as guest graphics, guest console, and the QEMU monitor in a
1771window. With this option, you can have QEMU listen on VNC display
1772@var{display} and redirect the VGA display over the VNC session. It is
1773very useful to enable the usb tablet device when using this option
Thomas Hutha358a3a2017-05-19 08:35:16 +02001774(option @option{-device usb-tablet}). When using the VNC display, you
Colin Lorddc0a3e42016-08-12 15:30:48 -04001775must use the @option{-k} parameter to set the keyboard layout if you are
1776not using en-us. Valid syntax for the @var{display} is
blueswir15824d652009-03-28 06:44:27 +00001777
Kevin Wolfb3f046c2009-10-09 10:58:35 +02001778@table @option
blueswir15824d652009-03-28 06:44:27 +00001779
Robert Ho99a9a522016-05-31 15:03:09 +08001780@item to=@var{L}
1781
1782With this option, QEMU will try next available VNC @var{display}s, until the
1783number @var{L}, if the origianlly defined "-vnc @var{display}" is not
1784available, e.g. port 5900+@var{display} is already used by another
1785application. By default, to=0.
1786
blueswir15824d652009-03-28 06:44:27 +00001787@item @var{host}:@var{d}
1788
1789TCP connections will only be allowed from @var{host} on display @var{d}.
1790By convention the TCP port is 5900+@var{d}. Optionally, @var{host} can
1791be omitted in which case the server will accept connections from any host.
1792
Kevin Wolf4e257e52009-10-09 10:58:36 +02001793@item unix:@var{path}
blueswir15824d652009-03-28 06:44:27 +00001794
1795Connections will be allowed over UNIX domain sockets where @var{path} is the
1796location of a unix socket to listen for connections on.
1797
1798@item none
1799
1800VNC is initialized but not started. The monitor @code{change} command
1801can be used to later start the VNC server.
1802
1803@end table
1804
1805Following the @var{display} value there may be one or more @var{option} flags
1806separated by commas. Valid options are
1807
Kevin Wolfb3f046c2009-10-09 10:58:35 +02001808@table @option
blueswir15824d652009-03-28 06:44:27 +00001809
1810@item reverse
1811
1812Connect to a listening VNC client via a ``reverse'' connection. The
1813client is specified by the @var{display}. For reverse network
1814connections (@var{host}:@var{d},@code{reverse}), the @var{d} argument
1815is a TCP port number, not a display number.
1816
Tim Hardeck7536ee42013-01-21 11:04:44 +01001817@item websocket
1818
1819Opens an additional TCP listening port dedicated to VNC Websocket connections.
Daniel P. Berrange275e0d62017-02-03 12:06:45 +00001820If a bare @var{websocket} option is given, the Websocket port is
18215700+@var{display}. An alternative port can be specified with the
1822syntax @code{websocket}=@var{port}.
1823
1824If @var{host} is specified connections will only be allowed from this host.
1825It is possible to control the websocket listen address independently, using
1826the syntax @code{websocket}=@var{host}:@var{port}.
1827
Daniel P. Berrange3e305e42015-08-06 14:39:32 +01001828If no TLS credentials are provided, the websocket connection runs in
1829unencrypted mode. If TLS credentials are provided, the websocket connection
1830requires encrypted client connections.
Tim Hardeck7536ee42013-01-21 11:04:44 +01001831
blueswir15824d652009-03-28 06:44:27 +00001832@item password
1833
1834Require that password based authentication is used for client connections.
Michal Novotny86ee5bc2012-07-16 15:54:38 +02001835
1836The password must be set separately using the @code{set_password} command in
1837the @ref{pcsys_monitor}. The syntax to change your password is:
1838@code{set_password <protocol> <password>} where <protocol> could be either
1839"vnc" or "spice".
1840
1841If you would like to change <protocol> password expiration, you should use
1842@code{expire_password <protocol> <expiration-time>} where expiration time could
1843be one of the following options: now, never, +seconds or UNIX time of
1844expiration, e.g. +60 to make password expire in 60 seconds, or 1335196800
1845to make password expire on "Mon Apr 23 12:00:00 EDT 2012" (UNIX time for this
1846date and time).
1847
1848You can also use keywords "now" or "never" for the expiration time to
1849allow <protocol> password to expire immediately or never expire.
blueswir15824d652009-03-28 06:44:27 +00001850
Daniel P. Berrange3e305e42015-08-06 14:39:32 +01001851@item tls-creds=@var{ID}
1852
1853Provides the ID of a set of TLS credentials to use to secure the
1854VNC server. They will apply to both the normal VNC server socket
1855and the websocket socket (if enabled). Setting TLS credentials
1856will cause the VNC server socket to enable the VeNCrypt auth
1857mechanism. The credentials should have been previously created
1858using the @option{-object tls-creds} argument.
1859
Daniel P. Berrange55cf09a2019-02-27 14:57:54 +00001860@item tls-authz=@var{ID}
1861
1862Provides the ID of the QAuthZ authorization object against which
1863the client's x509 distinguished name will validated. This object is
1864only resolved at time of use, so can be deleted and recreated on the
1865fly while the VNC server is active. If missing, it will default
1866to denying access.
1867
blueswir15824d652009-03-28 06:44:27 +00001868@item sasl
1869
1870Require that the client use SASL to authenticate with the VNC server.
1871The exact choice of authentication method used is controlled from the
1872system / user's SASL configuration file for the 'qemu' service. This
1873is typically found in /etc/sasl2/qemu.conf. If running QEMU as an
1874unprivileged user, an environment variable SASL_CONF_PATH can be used
1875to make it search alternate locations for the service config.
1876While some SASL auth methods can also provide data encryption (eg GSSAPI),
1877it is recommended that SASL always be combined with the 'tls' and
1878'x509' settings to enable use of SSL and server certificates. This
1879ensures a data encryption preventing compromise of authentication
1880credentials. See the @ref{vnc_security} section for details on using
1881SASL authentication.
1882
Daniel P. Berrange55cf09a2019-02-27 14:57:54 +00001883@item sasl-authz=@var{ID}
1884
1885Provides the ID of the QAuthZ authorization object against which
1886the client's SASL username will validated. This object is
1887only resolved at time of use, so can be deleted and recreated on the
1888fly while the VNC server is active. If missing, it will default
1889to denying access.
1890
blueswir15824d652009-03-28 06:44:27 +00001891@item acl
1892
Daniel P. Berrange55cf09a2019-02-27 14:57:54 +00001893Legacy method for enabling authorization of clients against the
1894x509 distinguished name and SASL username. It results in the creation
1895of two @code{authz-list} objects with IDs of @code{vnc.username} and
1896@code{vnc.x509dname}. The rules for these objects must be configured
1897with the HMP ACL commands.
1898
1899This option is deprecated and should no longer be used. The new
1900@option{sasl-authz} and @option{tls-authz} options are a
1901replacement.
blueswir15824d652009-03-28 06:44:27 +00001902
Corentin Chary6f9c78c2010-07-07 20:57:51 +02001903@item lossy
1904
1905Enable lossy compression methods (gradient, JPEG, ...). If this
1906option is set, VNC client may receive lossy framebuffer updates
1907depending on its encoding settings. Enabling this option can save
1908a lot of bandwidth at the expense of quality.
1909
Corentin Chary80e0c8c2011-02-04 09:06:08 +01001910@item non-adaptive
1911
1912Disable adaptive encodings. Adaptive encodings are enabled by default.
1913An adaptive encoding will try to detect frequently updated screen regions,
1914and send updates in these regions using a lossy encoding (like JPEG).
Stefan Weil61cc8702011-04-13 22:45:22 +02001915This can be really helpful to save bandwidth when playing videos. Disabling
Michael Tokarev9d85d552014-04-07 13:34:58 +04001916adaptive encodings restores the original static behavior of encodings
Corentin Chary80e0c8c2011-02-04 09:06:08 +01001917like Tight.
1918
Gerd Hoffmann8cf36482011-11-24 18:10:49 +01001919@item share=[allow-exclusive|force-shared|ignore]
1920
1921Set display sharing policy. 'allow-exclusive' allows clients to ask
1922for exclusive access. As suggested by the rfb spec this is
1923implemented by dropping other connections. Connecting multiple
1924clients in parallel requires all clients asking for a shared session
1925(vncviewer: -shared switch). This is the default. 'force-shared'
1926disables exclusive client access. Useful for shared desktop sessions,
1927where you don't want someone forgetting specify -shared disconnect
1928everybody else. 'ignore' completely ignores the shared flag and
1929allows everybody connect unconditionally. Doesn't conform to the rfb
Stefan Weilb65ee4f2012-05-11 22:25:50 +02001930spec but is traditional QEMU behavior.
Gerd Hoffmann8cf36482011-11-24 18:10:49 +01001931
Gerd Hoffmannc5ce8332016-06-01 08:22:30 +02001932@item key-delay-ms
1933
1934Set keyboard delay, for key down and key up events, in milliseconds.
Alexander Grafd3b0db62017-07-12 14:43:45 +02001935Default is 10. Keyboards are low-bandwidth devices, so this slowdown
Gerd Hoffmannc5ce8332016-06-01 08:22:30 +02001936can help the device and guest to keep up and not lose events in case
1937events are arriving in bulk. Possible causes for the latter are flaky
1938network connections, or scripts for automated testing.
1939
blueswir15824d652009-03-28 06:44:27 +00001940@end table
1941ETEXI
1942
1943STEXI
1944@end table
1945ETEXI
Michael Ellermana3adb7a2011-12-19 17:19:31 +11001946ARCHHEADING(, QEMU_ARCH_I386)
blueswir15824d652009-03-28 06:44:27 +00001947
Markus Armbrusterde6b4f92017-10-02 16:03:00 +02001948ARCHHEADING(i386 target only:, QEMU_ARCH_I386)
blueswir15824d652009-03-28 06:44:27 +00001949STEXI
1950@table @option
1951ETEXI
1952
blueswir15824d652009-03-28 06:44:27 +00001953DEF("win2k-hack", 0, QEMU_OPTION_win2k_hack,
Blue Swirlad960902010-03-29 19:23:52 +00001954 "-win2k-hack use it when installing Windows 2000 to avoid a disk full bug\n",
1955 QEMU_ARCH_I386)
blueswir15824d652009-03-28 06:44:27 +00001956STEXI
1957@item -win2k-hack
Stefan Weil6616b2a2010-02-05 23:52:05 +01001958@findex -win2k-hack
blueswir15824d652009-03-28 06:44:27 +00001959Use it when installing Windows 2000 to avoid a disk full bug. After
1960Windows 2000 is installed, you no longer need this option (this option
1961slows down the IDE transfers).
1962ETEXI
1963
blueswir15824d652009-03-28 06:44:27 +00001964DEF("no-fd-bootchk", 0, QEMU_OPTION_no_fd_bootchk,
Blue Swirlad960902010-03-29 19:23:52 +00001965 "-no-fd-bootchk disable boot signature checking for floppy disks\n",
1966 QEMU_ARCH_I386)
blueswir15824d652009-03-28 06:44:27 +00001967STEXI
1968@item -no-fd-bootchk
Stefan Weil6616b2a2010-02-05 23:52:05 +01001969@findex -no-fd-bootchk
Markus Armbruster4eda32f2013-06-14 13:15:06 +02001970Disable boot signature checking for floppy disks in BIOS. May
blueswir15824d652009-03-28 06:44:27 +00001971be needed to boot from old floppy disks.
1972ETEXI
1973
blueswir15824d652009-03-28 06:44:27 +00001974DEF("no-acpi", 0, QEMU_OPTION_no_acpi,
Shannon Zhaof5d8c8c2015-05-29 11:28:54 +01001975 "-no-acpi disable ACPI\n", QEMU_ARCH_I386 | QEMU_ARCH_ARM)
blueswir15824d652009-03-28 06:44:27 +00001976STEXI
1977@item -no-acpi
Stefan Weil6616b2a2010-02-05 23:52:05 +01001978@findex -no-acpi
blueswir15824d652009-03-28 06:44:27 +00001979Disable ACPI (Advanced Configuration and Power Interface) support. Use
1980it if your guest OS complains about ACPI problems (PC target machine
1981only).
1982ETEXI
1983
blueswir15824d652009-03-28 06:44:27 +00001984DEF("no-hpet", 0, QEMU_OPTION_no_hpet,
Blue Swirlad960902010-03-29 19:23:52 +00001985 "-no-hpet disable HPET\n", QEMU_ARCH_I386)
blueswir15824d652009-03-28 06:44:27 +00001986STEXI
1987@item -no-hpet
Stefan Weil6616b2a2010-02-05 23:52:05 +01001988@findex -no-hpet
blueswir15824d652009-03-28 06:44:27 +00001989Disable HPET support.
1990ETEXI
1991
blueswir15824d652009-03-28 06:44:27 +00001992DEF("acpitable", HAS_ARG, QEMU_OPTION_acpitable,
Michael Tokarev104bf022011-05-12 18:44:17 +04001993 "-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 +00001994 " ACPI table description\n", QEMU_ARCH_I386)
blueswir15824d652009-03-28 06:44:27 +00001995STEXI
1996@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 +01001997@findex -acpitable
blueswir15824d652009-03-28 06:44:27 +00001998Add ACPI table with specified header fields and context from specified files.
Michael Tokarev104bf022011-05-12 18:44:17 +04001999For file=, take whole ACPI table from the specified files, including all
2000ACPI headers (possible overridden by other options).
2001For data=, only data
2002portion of the table is used, all header information is specified in the
2003command line.
Laszlo Ersekae123742016-01-18 15:12:13 +01002004If a SLIC table is supplied to QEMU, then the SLIC's oem_id and oem_table_id
2005fields will override the same in the RSDT and the FADT (a.k.a. FACP), in order
2006to ensure the field matches required by the Microsoft SLIC spec and the ACPI
2007spec.
blueswir15824d652009-03-28 06:44:27 +00002008ETEXI
2009
aliguorib6f6e3d2009-04-17 18:59:56 +00002010DEF("smbios", HAS_ARG, QEMU_OPTION_smbios,
2011 "-smbios file=binary\n"
Bruce Rogersca1a8a02010-01-06 12:33:57 -07002012 " load SMBIOS entry from binary file\n"
Gabriel L. Somlob155eb12015-02-05 11:45:30 -05002013 "-smbios type=0[,vendor=str][,version=str][,date=str][,release=%d.%d]\n"
2014 " [,uefi=on|off]\n"
Bruce Rogersca1a8a02010-01-06 12:33:57 -07002015 " specify SMBIOS type 0 fields\n"
aliguorib6f6e3d2009-04-17 18:59:56 +00002016 "-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str]\n"
2017 " [,uuid=uuid][,sku=str][,family=str]\n"
Gabriel L. Somlob155eb12015-02-05 11:45:30 -05002018 " specify SMBIOS type 1 fields\n"
2019 "-smbios type=2[,manufacturer=str][,product=str][,version=str][,serial=str]\n"
2020 " [,asset=str][,location=str]\n"
2021 " specify SMBIOS type 2 fields\n"
2022 "-smbios type=3[,manufacturer=str][,version=str][,serial=str][,asset=str]\n"
2023 " [,sku=str]\n"
2024 " specify SMBIOS type 3 fields\n"
2025 "-smbios type=4[,sock_pfx=str][,manufacturer=str][,version=str][,serial=str]\n"
2026 " [,asset=str][,part=str]\n"
2027 " specify SMBIOS type 4 fields\n"
2028 "-smbios type=17[,loc_pfx=str][,bank=str][,manufacturer=str][,serial=str]\n"
Gabriel L. Somlo3ebd6cc2015-03-11 13:58:01 -04002029 " [,asset=str][,part=str][,speed=%d]\n"
Gabriel L. Somlob155eb12015-02-05 11:45:30 -05002030 " specify SMBIOS type 17 fields\n",
Wei Huangc30e1562015-09-07 10:39:29 +01002031 QEMU_ARCH_I386 | QEMU_ARCH_ARM)
aliguorib6f6e3d2009-04-17 18:59:56 +00002032STEXI
2033@item -smbios file=@var{binary}
Stefan Weil6616b2a2010-02-05 23:52:05 +01002034@findex -smbios
aliguorib6f6e3d2009-04-17 18:59:56 +00002035Load SMBIOS entry from binary file.
2036
Gabriel L. Somlo84351842014-05-19 10:09:54 -04002037@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 +00002038Specify SMBIOS type 0 fields
2039
Gabriel L. Somlob155eb12015-02-05 11:45:30 -05002040@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 +00002041Specify SMBIOS type 1 fields
Gabriel L. Somlob155eb12015-02-05 11:45:30 -05002042
2043@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}]
2044Specify SMBIOS type 2 fields
2045
2046@item -smbios type=3[,manufacturer=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,sku=@var{str}]
2047Specify SMBIOS type 3 fields
2048
2049@item -smbios type=4[,sock_pfx=@var{str}][,manufacturer=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,part=@var{str}]
2050Specify SMBIOS type 4 fields
2051
Gabriel L. Somlo3ebd6cc2015-03-11 13:58:01 -04002052@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 -05002053Specify SMBIOS type 17 fields
aliguorib6f6e3d2009-04-17 18:59:56 +00002054ETEXI
2055
blueswir15824d652009-03-28 06:44:27 +00002056STEXI
2057@end table
2058ETEXI
Markus Armbrusterc70a01e2013-02-13 19:49:40 +01002059DEFHEADING()
blueswir15824d652009-03-28 06:44:27 +00002060
Markus Armbrusterde6b4f92017-10-02 16:03:00 +02002061DEFHEADING(Network options:)
blueswir15824d652009-03-28 06:44:27 +00002062STEXI
2063@table @option
2064ETEXI
2065
Thomas Huth6a8b4a52015-05-15 16:58:24 +02002066DEF("netdev", HAS_ARG, QEMU_OPTION_netdev,
blueswir15824d652009-03-28 06:44:27 +00002067#ifdef CONFIG_SLIRP
Samuel Thibault0b11c032016-03-20 12:29:54 +01002068 "-netdev user,id=str[,ipv4[=on|off]][,net=addr[/mask]][,host=addr]\n"
2069 " [,ipv6[=on|off]][,ipv6-net=addr[/int]][,ipv6-host=addr]\n"
2070 " [,restrict=on|off][,hostname=host][,dhcpstart=addr]\n"
Benjamin Drungf18d1372018-02-27 17:06:01 +01002071 " [,dns=addr][,ipv6-dns=addr][,dnssearch=domain][,domainname=domain]\n"
Fam Zheng0fca92b2018-09-14 15:26:16 +08002072 " [,tftp=dir][,tftp-server-name=name][,bootfile=f][,hostfwd=rule][,guestfwd=rule]"
Jan Kiszkaad196a92009-06-24 14:42:28 +02002073#ifndef _WIN32
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02002074 "[,smb=dir[,smbserver=addr]]\n"
Jan Kiszkaad196a92009-06-24 14:42:28 +02002075#endif
Thomas Huth6a8b4a52015-05-15 16:58:24 +02002076 " configure a user mode network backend with ID 'str',\n"
2077 " its DHCP server and optional services\n"
blueswir15824d652009-03-28 06:44:27 +00002078#endif
2079#ifdef _WIN32
Thomas Huth6a8b4a52015-05-15 16:58:24 +02002080 "-netdev tap,id=str,ifname=name\n"
2081 " configure a host TAP network backend with ID 'str'\n"
blueswir15824d652009-03-28 06:44:27 +00002082#else
Thomas Huth6a8b4a52015-05-15 16:58:24 +02002083 "-netdev tap,id=str[,fd=h][,fds=x:y:...:z][,ifname=name][,script=file][,downscript=dfile]\n"
Alexey Kardashevskiy584613e2016-09-13 17:11:54 +10002084 " [,br=bridge][,helper=helper][,sndbuf=nbytes][,vnet_hdr=on|off][,vhost=on|off]\n"
Thomas Huth6a8b4a52015-05-15 16:58:24 +02002085 " [,vhostfd=h][,vhostfds=x:y:...:z][,vhostforce=on|off][,queues=n]\n"
Jason Wang69e87b32016-07-06 09:57:55 +08002086 " [,poll-us=n]\n"
Thomas Huth6a8b4a52015-05-15 16:58:24 +02002087 " configure a host TAP network backend with ID 'str'\n"
Alexey Kardashevskiy584613e2016-09-13 17:11:54 +10002088 " connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n"
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002089 " use network scripts 'file' (default=" DEFAULT_NETWORK_SCRIPT ")\n"
2090 " to configure it and 'dfile' (default=" DEFAULT_NETWORK_DOWN_SCRIPT ")\n"
2091 " to deconfigure it\n"
Bruce Rogersca1a8a02010-01-06 12:33:57 -07002092 " use '[down]script=no' to disable script execution\n"
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002093 " use network helper 'helper' (default=" DEFAULT_BRIDGE_HELPER ") to\n"
2094 " configure it\n"
blueswir15824d652009-03-28 06:44:27 +00002095 " use 'fd=h' to connect to an already opened TAP interface\n"
Jason Wang2ca81ba2013-02-20 18:04:01 +08002096 " use 'fds=x:y:...:z' to connect to already opened multiqueue capable TAP interfaces\n"
Bruce Rogersca1a8a02010-01-06 12:33:57 -07002097 " use 'sndbuf=nbytes' to limit the size of the send buffer (the\n"
Michael S. Tsirkinf157ed22011-02-01 14:25:40 +02002098 " default is disabled 'sndbuf=0' to enable flow control set 'sndbuf=1048576')\n"
Bruce Rogersca1a8a02010-01-06 12:33:57 -07002099 " use vnet_hdr=off to avoid enabling the IFF_VNET_HDR tap flag\n"
2100 " 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 +02002101 " use vhost=on to enable experimental in kernel accelerator\n"
mst@redhat.com5430a282011-02-01 22:13:42 +02002102 " (only has effect for virtio guests which use MSIX)\n"
2103 " use vhostforce=on to force vhost on for non-MSIX virtio guests\n"
Michael S. Tsirkin82b0d802010-03-17 13:08:24 +02002104 " use 'vhostfd=h' to connect to an already opened vhost net device\n"
Jason Wang2ca81ba2013-02-20 18:04:01 +08002105 " use 'vhostfds=x:y:...:z to connect to multiple already opened vhost net devices\n"
Jason Wangec396012013-02-22 22:57:52 +08002106 " use 'queues=n' to specify the number of queues to be created for multiqueue TAP\n"
Jason Wang69e87b32016-07-06 09:57:55 +08002107 " use 'poll-us=n' to speciy the maximum number of microseconds that could be\n"
2108 " spent on busy polling for vhost net\n"
Thomas Huth6a8b4a52015-05-15 16:58:24 +02002109 "-netdev bridge,id=str[,br=bridge][,helper=helper]\n"
2110 " configure a host TAP network backend with ID 'str' that is\n"
2111 " connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n"
2112 " using the program 'helper (default=" DEFAULT_BRIDGE_HELPER ")\n"
Mark McLoughlin0df0ff62009-06-18 18:21:34 +01002113#endif
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01002114#ifdef __linux__
Thomas Huth6a8b4a52015-05-15 16:58:24 +02002115 "-netdev l2tpv3,id=str,src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport]\n"
2116 " [,rxsession=rxsession],txsession=txsession[,ipv6=on/off][,udp=on/off]\n"
2117 " [,cookie64=on/off][,counter][,pincounter][,txcookie=txcookie]\n"
2118 " [,rxcookie=rxcookie][,offset=offset]\n"
2119 " configure a network backend with ID 'str' connected to\n"
2120 " an Ethernet over L2TPv3 pseudowire.\n"
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01002121 " Linux kernel 3.3+ as well as most routers can talk\n"
Michael Tokarev2f47b402014-07-24 20:10:17 +04002122 " L2TPv3. This transport allows connecting a VM to a VM,\n"
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01002123 " VM to a router and even VM to Host. It is a nearly-universal\n"
2124 " standard (RFC3391). Note - this implementation uses static\n"
2125 " pre-configured tunnels (same as the Linux kernel).\n"
2126 " use 'src=' to specify source address\n"
2127 " use 'dst=' to specify destination address\n"
2128 " use 'udp=on' to specify udp encapsulation\n"
Gonglei39526512014-08-14 14:35:48 +08002129 " use 'srcport=' to specify source udp port\n"
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01002130 " use 'dstport=' to specify destination udp port\n"
2131 " use 'ipv6=on' to force v6\n"
2132 " L2TPv3 uses cookies to prevent misconfiguration as\n"
2133 " well as a weak security measure\n"
2134 " use 'rxcookie=0x012345678' to specify a rxcookie\n"
2135 " use 'txcookie=0x012345678' to specify a txcookie\n"
2136 " use 'cookie64=on' to set cookie size to 64 bit, otherwise 32\n"
2137 " use 'counter=off' to force a 'cut-down' L2TPv3 with no counter\n"
2138 " use 'pincounter=on' to work around broken counter handling in peer\n"
2139 " use 'offset=X' to add an extra offset between header and data\n"
2140#endif
Thomas Huth6a8b4a52015-05-15 16:58:24 +02002141 "-netdev socket,id=str[,fd=h][,listen=[host]:port][,connect=host:port]\n"
2142 " configure a network backend to connect to another network\n"
2143 " using a socket connection\n"
2144 "-netdev socket,id=str[,fd=h][,mcast=maddr:port[,localaddr=addr]]\n"
2145 " configure a network backend to connect to a multicast maddr and port\n"
Mike Ryan3a75e742010-12-01 11:16:47 -08002146 " use 'localaddr=addr' to specify the host address to send packets from\n"
Thomas Huth6a8b4a52015-05-15 16:58:24 +02002147 "-netdev socket,id=str[,fd=h][,udp=host:port][,localaddr=host:port]\n"
2148 " configure a network backend to connect to another network\n"
2149 " using an UDP tunnel\n"
blueswir15824d652009-03-28 06:44:27 +00002150#ifdef CONFIG_VDE
Thomas Huth6a8b4a52015-05-15 16:58:24 +02002151 "-netdev vde,id=str[,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]\n"
2152 " configure a network backend to connect to port 'n' of a vde switch\n"
2153 " running on host and listening for incoming connections on 'socketpath'.\n"
blueswir15824d652009-03-28 06:44:27 +00002154 " Use group 'groupname' and mode 'octalmode' to change default\n"
2155 " ownership and permissions for communication port.\n"
2156#endif
Vincenzo Maffione58952132013-11-06 11:44:06 +01002157#ifdef CONFIG_NETMAP
Thomas Huth6a8b4a52015-05-15 16:58:24 +02002158 "-netdev netmap,id=str,ifname=name[,devname=nmname]\n"
Vincenzo Maffione58952132013-11-06 11:44:06 +01002159 " attach to the existing netmap-enabled network interface 'name', or to a\n"
2160 " VALE port (created on the fly) called 'name' ('nmname' is name of the \n"
2161 " netmap device, defaults to '/dev/netmap')\n"
2162#endif
Thomas Huth253dc142018-02-21 11:18:32 +01002163#ifdef CONFIG_POSIX
Thomas Huth6a8b4a52015-05-15 16:58:24 +02002164 "-netdev vhost-user,id=str,chardev=dev[,vhostforce=on|off]\n"
2165 " configure a vhost-user network, backed by a chardev 'dev'\n"
Thomas Huth253dc142018-02-21 11:18:32 +01002166#endif
Thomas Huth18d65d22018-01-15 20:50:55 +01002167 "-netdev hubport,id=str,hubid=n[,netdev=nd]\n"
Thomas Huthaf1a5c32018-04-30 20:02:23 +02002168 " configure a hub port on the hub with ID 'n'\n", QEMU_ARCH_ALL)
Thomas Huth78cd6f72018-02-21 11:18:36 +01002169DEF("nic", HAS_ARG, QEMU_OPTION_nic,
BALATON Zoltandfaa7d52018-07-16 21:12:08 +02002170 "-nic [tap|bridge|"
Thomas Huth78cd6f72018-02-21 11:18:36 +01002171#ifdef CONFIG_SLIRP
2172 "user|"
2173#endif
2174#ifdef __linux__
2175 "l2tpv3|"
2176#endif
2177#ifdef CONFIG_VDE
2178 "vde|"
2179#endif
2180#ifdef CONFIG_NETMAP
2181 "netmap|"
2182#endif
2183#ifdef CONFIG_POSIX
2184 "vhost-user|"
2185#endif
2186 "socket][,option][,...][mac=macaddr]\n"
2187 " initialize an on-board / default host NIC (using MAC address\n"
2188 " macaddr) and connect it to the given host network backend\n"
BALATON Zoltandfaa7d52018-07-16 21:12:08 +02002189 "-nic none use it alone to have zero network devices (the default is to\n"
Thomas Huth78cd6f72018-02-21 11:18:36 +01002190 " provided a 'user' network connection)\n",
2191 QEMU_ARCH_ALL)
Thomas Huth6a8b4a52015-05-15 16:58:24 +02002192DEF("net", HAS_ARG, QEMU_OPTION_net,
Thomas Huthaf1a5c32018-04-30 20:02:23 +02002193 "-net nic[,macaddr=mac][,model=type][,name=str][,addr=str][,vectors=v]\n"
Thomas Huth0e60a822017-12-19 16:28:55 +01002194 " configure or create an on-board (or machine default) NIC and\n"
Thomas Huthaf1a5c32018-04-30 20:02:23 +02002195 " connect it to hub 0 (please use -nic unless you need a hub)\n"
Thomas Huth6a8b4a52015-05-15 16:58:24 +02002196 "-net ["
Mark McLoughlina1ea4582009-10-08 19:58:26 +01002197#ifdef CONFIG_SLIRP
2198 "user|"
2199#endif
2200 "tap|"
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002201 "bridge|"
Mark McLoughlina1ea4582009-10-08 19:58:26 +01002202#ifdef CONFIG_VDE
2203 "vde|"
2204#endif
Vincenzo Maffione58952132013-11-06 11:44:06 +01002205#ifdef CONFIG_NETMAP
2206 "netmap|"
2207#endif
Thomas Huthaf1a5c32018-04-30 20:02:23 +02002208 "socket][,option][,option][,...]\n"
Thomas Huth6a8b4a52015-05-15 16:58:24 +02002209 " old way to initialize a host network interface\n"
2210 " (use the -netdev option if possible instead)\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00002211STEXI
Thomas Huthabbbb032018-03-12 13:20:50 +01002212@item -nic [tap|bridge|user|l2tpv3|vde|netmap|vhost-user|socket][,...][,mac=macaddr][,model=mn]
2213@findex -nic
2214This option is a shortcut for configuring both the on-board (default) guest
2215NIC hardware and the host network backend in one go. The host backend options
2216are the same as with the corresponding @option{-netdev} options below.
2217The guest NIC model can be set with @option{model=@var{modelname}}.
2218Use @option{model=help} to list the available device types.
2219The hardware MAC address can be set with @option{mac=@var{macaddr}}.
2220
2221The following two example do exactly the same, to show how @option{-nic} can
2222be used to shorten the command line length (note that the e1000 is the default
2223on i386, so the @option{model=e1000} parameter could even be omitted here, too):
2224@example
2225qemu-system-i386 -netdev user,id=n1,ipv6=off -device e1000,netdev=n1,mac=52:54:98:76:54:32
2226qemu-system-i386 -nic user,ipv6=off,model=e1000,mac=52:54:98:76:54:32
2227@end example
2228
2229@item -nic none
2230Indicate that no network devices should be configured. It is used to override
2231the default configuration (default NIC with ``user'' host network backend)
2232which is activated if no other networking options are provided.
blueswir15824d652009-03-28 06:44:27 +00002233
Stefan Hajnoczi08d12022012-08-14 14:14:27 +01002234@item -netdev user,id=@var{id}[,@var{option}][,@var{option}][,...]
Markus Armbrusterb8f490e2013-02-13 19:49:38 +01002235@findex -netdev
Thomas Huthabbbb032018-03-12 13:20:50 +01002236Configure user mode host network backend which requires no administrator
Jan Kiszkaad196a92009-06-24 14:42:28 +02002237privilege to run. Valid options are:
blueswir15824d652009-03-28 06:44:27 +00002238
Kevin Wolfb3f046c2009-10-09 10:58:35 +02002239@table @option
Stefan Hajnoczi08d12022012-08-14 14:14:27 +01002240@item id=@var{id}
Jan Kiszkaad196a92009-06-24 14:42:28 +02002241Assign symbolic name for use in monitor commands.
2242
Thomas Huthabbbb032018-03-12 13:20:50 +01002243@item ipv4=on|off and ipv6=on|off
2244Specify that either IPv4 or IPv6 must be enabled. If neither is specified
2245both protocols are enabled.
Samuel Thibault0b11c032016-03-20 12:29:54 +01002246
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02002247@item net=@var{addr}[/@var{mask}]
2248Set IP network address the guest will see. Optionally specify the netmask,
2249either in the form a.b.c.d or as number of valid top-most bits. Default is
Brad Hardsb0b36e52011-04-24 17:19:56 +1000225010.0.2.0/24.
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02002251
2252@item host=@var{addr}
2253Specify the guest-visible address of the host. Default is the 2nd IP in the
2254guest network, i.e. x.x.x.2.
Jan Kiszkaad196a92009-06-24 14:42:28 +02002255
Samuel Thibaultd8eb3862016-03-25 00:02:58 +01002256@item ipv6-net=@var{addr}[/@var{int}]
2257Set IPv6 network address the guest will see (default is fec0::/64). The
2258network prefix is given in the usual hexadecimal IPv6 address
2259notation. The prefix size is optional, and is given as the number of
2260valid top-most bits (default is 64).
Yann Bordenave7aac5312016-03-15 10:31:22 +01002261
Samuel Thibaultd8eb3862016-03-25 00:02:58 +01002262@item ipv6-host=@var{addr}
Yann Bordenave7aac5312016-03-15 10:31:22 +01002263Specify the guest-visible IPv6 address of the host. Default is the 2nd IPv6 in
2264the guest network, i.e. xxxx::2.
2265
Jan Kiszkac54ed5b2011-07-20 12:20:14 +02002266@item restrict=on|off
Brad Hardscaef55e2011-06-09 07:50:43 +10002267If this option is enabled, the guest will be isolated, i.e. it will not be
Jan Kiszkaad196a92009-06-24 14:42:28 +02002268able to contact the host and no guest IP packets will be routed over the host
Brad Hardscaef55e2011-06-09 07:50:43 +10002269to the outside. This option does not affect any explicitly set forwarding rules.
Jan Kiszkaad196a92009-06-24 14:42:28 +02002270
2271@item hostname=@var{name}
Klaus Stengel63d29602012-10-27 19:53:39 +02002272Specifies the client hostname reported by the built-in DHCP server.
Jan Kiszkaad196a92009-06-24 14:42:28 +02002273
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02002274@item dhcpstart=@var{addr}
2275Specify the first of the 16 IPs the built-in DHCP server can assign. Default
Brad Hardsb0b36e52011-04-24 17:19:56 +10002276is 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 +02002277
2278@item dns=@var{addr}
2279Specify the guest-visible address of the virtual nameserver. The address must
2280be different from the host address. Default is the 3rd IP in the guest network,
2281i.e. x.x.x.3.
2282
Samuel Thibaultd8eb3862016-03-25 00:02:58 +01002283@item ipv6-dns=@var{addr}
Yann Bordenave7aac5312016-03-15 10:31:22 +01002284Specify the guest-visible address of the IPv6 virtual nameserver. The address
2285must be different from the host address. Default is the 3rd IP in the guest
2286network, i.e. xxxx::3.
2287
Klaus Stengel63d29602012-10-27 19:53:39 +02002288@item dnssearch=@var{domain}
2289Provides an entry for the domain-search list sent by the built-in
2290DHCP server. More than one domain suffix can be transmitted by specifying
2291this option multiple times. If supported, this will cause the guest to
2292automatically try to append the given domain suffix(es) in case a domain name
2293can not be resolved.
2294
2295Example:
2296@example
Thomas Huthabbbb032018-03-12 13:20:50 +01002297qemu-system-i386 -nic user,dnssearch=mgmt.example.org,dnssearch=example.org
Klaus Stengel63d29602012-10-27 19:53:39 +02002298@end example
2299
Benjamin Drungf18d1372018-02-27 17:06:01 +01002300@item domainname=@var{domain}
2301Specifies the client domain name reported by the built-in DHCP server.
2302
Jan Kiszkaad196a92009-06-24 14:42:28 +02002303@item tftp=@var{dir}
2304When using the user mode network stack, activate a built-in TFTP
2305server. The files in @var{dir} will be exposed as the root of a TFTP server.
2306The TFTP client on the guest must be configured in binary mode (use the command
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02002307@code{bin} of the Unix TFTP client).
Jan Kiszkaad196a92009-06-24 14:42:28 +02002308
Fam Zheng0fca92b2018-09-14 15:26:16 +08002309@item tftp-server-name=@var{name}
2310In BOOTP reply, broadcast @var{name} as the "TFTP server name" (RFC2132 option
231166). This can be used to advise the guest to load boot files or configurations
2312from a different server than the host address.
2313
Jan Kiszkaad196a92009-06-24 14:42:28 +02002314@item bootfile=@var{file}
2315When using the user mode network stack, broadcast @var{file} as the BOOTP
2316filename. In conjunction with @option{tftp}, this can be used to network boot
2317a guest from a local directory.
2318
2319Example (using pxelinux):
2320@example
Thomas Huthabbbb032018-03-12 13:20:50 +01002321qemu-system-i386 -hda linux.img -boot n -device e1000,netdev=n1 \
2322 -netdev user,id=n1,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
Jan Kiszkaad196a92009-06-24 14:42:28 +02002323@end example
2324
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02002325@item smb=@var{dir}[,smbserver=@var{addr}]
Jan Kiszkaad196a92009-06-24 14:42:28 +02002326When using the user mode network stack, activate a built-in SMB
2327server so that Windows OSes can access to the host files in @file{@var{dir}}
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02002328transparently. The IP address of the SMB server can be set to @var{addr}. By
2329default the 4th IP in the guest network is used, i.e. x.x.x.4.
Jan Kiszkaad196a92009-06-24 14:42:28 +02002330
2331In the guest Windows OS, the line:
2332@example
233310.0.2.4 smbserver
2334@end example
2335must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me)
2336or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000).
2337
2338Then @file{@var{dir}} can be accessed in @file{\\smbserver\qemu}.
2339
Brade2d88302011-09-02 16:53:28 -04002340Note that a SAMBA server must be installed on the host OS.
Jan Kiszkaad196a92009-06-24 14:42:28 +02002341
Jan Kiszka3c6a0582009-06-24 14:42:28 +02002342@item hostfwd=[tcp|udp]:[@var{hostaddr}]:@var{hostport}-[@var{guestaddr}]:@var{guestport}
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02002343Redirect incoming TCP or UDP connections to the host port @var{hostport} to
2344the guest IP address @var{guestaddr} on guest port @var{guestport}. If
2345@var{guestaddr} is not specified, its value is x.x.x.15 (default first address
Jan Kiszka3c6a0582009-06-24 14:42:28 +02002346given by the built-in DHCP server). By specifying @var{hostaddr}, the rule can
2347be bound to a specific host interface. If no connection type is set, TCP is
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02002348used. This option can be given multiple times.
Jan Kiszkaad196a92009-06-24 14:42:28 +02002349
2350For example, to redirect host X11 connection from screen 1 to guest
2351screen 0, use the following:
2352
2353@example
2354# on the host
Thomas Huthabbbb032018-03-12 13:20:50 +01002355qemu-system-i386 -nic user,hostfwd=tcp:127.0.0.1:6001-:6000
Jan Kiszkaad196a92009-06-24 14:42:28 +02002356# this host xterm should open in the guest X11 server
2357xterm -display :1
2358@end example
2359
2360To redirect telnet connections from host port 5555 to telnet port on
2361the guest, use the following:
2362
2363@example
2364# on the host
Thomas Huthabbbb032018-03-12 13:20:50 +01002365qemu-system-i386 -nic user,hostfwd=tcp::5555-:23
Jan Kiszkaad196a92009-06-24 14:42:28 +02002366telnet localhost 5555
2367@end example
2368
2369Then when you use on the host @code{telnet localhost 5555}, you
2370connect to the guest telnet server.
2371
Jan Kiszkac92ef6a2009-06-24 14:42:28 +02002372@item guestfwd=[tcp]:@var{server}:@var{port}-@var{dev}
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02002373@itemx guestfwd=[tcp]:@var{server}:@var{port}-@var{cmd:command}
Jan Kiszka3c6a0582009-06-24 14:42:28 +02002374Forward guest TCP connections to the IP address @var{server} on port @var{port}
Alexander Grafb412eb62012-06-03 09:45:01 +02002375to the character device @var{dev} or to a program executed by @var{cmd:command}
2376which gets spawned for each connection. This option can be given multiple times.
2377
Stefan Weil43ffe612012-07-20 23:26:02 +02002378You can either use a chardev directly and have that one used throughout QEMU's
Alexander Grafb412eb62012-06-03 09:45:01 +02002379lifetime, like in the following example:
2380
2381@example
2382# open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever
2383# the guest accesses it
Thomas Huthabbbb032018-03-12 13:20:50 +01002384qemu-system-i386 -nic user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321
Alexander Grafb412eb62012-06-03 09:45:01 +02002385@end example
2386
2387Or you can execute a command on every TCP connection established by the guest,
Stefan Weil43ffe612012-07-20 23:26:02 +02002388so that QEMU behaves similar to an inetd process for that virtual server:
Alexander Grafb412eb62012-06-03 09:45:01 +02002389
2390@example
2391# call "netcat 10.10.1.1 4321" on every TCP connection to 10.0.2.100:1234
2392# and connect the TCP stream to its stdin/stdout
Thomas Huthabbbb032018-03-12 13:20:50 +01002393qemu-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 +02002394@end example
Jan Kiszkaad196a92009-06-24 14:42:28 +02002395
2396@end table
2397
Alexey Kardashevskiy584613e2016-09-13 17:11:54 +10002398@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 +01002399Configure a host TAP network backend with ID @var{id}.
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002400
2401Use the network script @var{file} to configure it and the network script
blueswir15824d652009-03-28 06:44:27 +00002402@var{dfile} to deconfigure it. If @var{name} is not provided, the OS
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002403automatically provides one. The default network configure script is
2404@file{/etc/qemu-ifup} and the default network deconfigure script is
2405@file{/etc/qemu-ifdown}. Use @option{script=no} or @option{downscript=no}
2406to disable script execution.
2407
2408If running QEMU as an unprivileged user, use the network helper
Alexey Kardashevskiy584613e2016-09-13 17:11:54 +10002409@var{helper} to configure the TAP interface and attach it to the bridge.
2410The default network helper executable is @file{/path/to/qemu-bridge-helper}
2411and the default bridge device is @file{br0}.
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002412
2413@option{fd}=@var{h} can be used to specify the handle of an already
2414opened host TAP interface.
2415
2416Examples:
blueswir15824d652009-03-28 06:44:27 +00002417
2418@example
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002419#launch a QEMU instance with the default network script
Thomas Huthabbbb032018-03-12 13:20:50 +01002420qemu-system-i386 linux.img -nic tap
blueswir15824d652009-03-28 06:44:27 +00002421@end example
2422
blueswir15824d652009-03-28 06:44:27 +00002423@example
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002424#launch a QEMU instance with two NICs, each one connected
2425#to a TAP device
Stefan Weil3804da92012-05-11 22:21:50 +02002426qemu-system-i386 linux.img \
Thomas Huth74f78b92018-01-15 08:40:17 +01002427 -netdev tap,id=nd0,ifname=tap0 -device e1000,netdev=nd0 \
2428 -netdev tap,id=nd1,ifname=tap1 -device rtl8139,netdev=nd1
blueswir15824d652009-03-28 06:44:27 +00002429@end example
2430
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002431@example
2432#launch a QEMU instance with the default network helper to
2433#connect a TAP device to bridge br0
Thomas Huthabbbb032018-03-12 13:20:50 +01002434qemu-system-i386 linux.img -device virtio-net-pci,netdev=n1 \
2435 -netdev tap,id=n1,"helper=/path/to/qemu-bridge-helper"
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002436@end example
2437
Stefan Hajnoczi08d12022012-08-14 14:14:27 +01002438@item -netdev bridge,id=@var{id}[,br=@var{bridge}][,helper=@var{helper}]
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002439Connect a host TAP network interface to a host bridge device.
2440
2441Use the network helper @var{helper} to configure the TAP interface and
2442attach it to the bridge. The default network helper executable is
Amos Kong420508f2013-10-23 04:49:28 +08002443@file{/path/to/qemu-bridge-helper} and the default bridge
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002444device is @file{br0}.
2445
2446Examples:
2447
2448@example
2449#launch a QEMU instance with the default network helper to
2450#connect a TAP device to bridge br0
Thomas Huthabbbb032018-03-12 13:20:50 +01002451qemu-system-i386 linux.img -netdev bridge,id=n1 -device virtio-net,netdev=n1
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002452@end example
2453
2454@example
2455#launch a QEMU instance with the default network helper to
2456#connect a TAP device to bridge qemubr0
Thomas Huthabbbb032018-03-12 13:20:50 +01002457qemu-system-i386 linux.img -netdev bridge,br=qemubr0,id=n1 -device virtio-net,netdev=n1
Corey Bryanta7c36ee2012-01-26 09:42:27 -05002458@end example
2459
Stefan Hajnoczi08d12022012-08-14 14:14:27 +01002460@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 +00002461
Thomas Huthabbbb032018-03-12 13:20:50 +01002462This host network backend can be used to connect the guest's network to
2463another QEMU virtual machine using a TCP socket connection. If @option{listen}
2464is specified, QEMU waits for incoming connections on @var{port}
blueswir15824d652009-03-28 06:44:27 +00002465(@var{host} is optional). @option{connect} is used to connect to
2466another QEMU instance using the @option{listen} option. @option{fd}=@var{h}
2467specifies an already opened TCP socket.
2468
2469Example:
2470@example
2471# launch a first QEMU instance
Stefan Weil3804da92012-05-11 22:21:50 +02002472qemu-system-i386 linux.img \
Thomas Huthabbbb032018-03-12 13:20:50 +01002473 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
2474 -netdev socket,id=n1,listen=:1234
2475# connect the network of this instance to the network of the first instance
Stefan Weil3804da92012-05-11 22:21:50 +02002476qemu-system-i386 linux.img \
Thomas Huthabbbb032018-03-12 13:20:50 +01002477 -device e1000,netdev=n2,mac=52:54:00:12:34:57 \
2478 -netdev socket,id=n2,connect=127.0.0.1:1234
blueswir15824d652009-03-28 06:44:27 +00002479@end example
2480
Stefan Hajnoczi08d12022012-08-14 14:14:27 +01002481@item -netdev socket,id=@var{id}[,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]]
blueswir15824d652009-03-28 06:44:27 +00002482
Thomas Huthabbbb032018-03-12 13:20:50 +01002483Configure a socket host network backend to share the guest's network traffic
2484with another QEMU virtual machines using a UDP multicast socket, effectively
2485making a bus for every QEMU with same multicast address @var{maddr} and @var{port}.
blueswir15824d652009-03-28 06:44:27 +00002486NOTES:
2487@enumerate
2488@item
2489Several QEMU can be running on different hosts and share same bus (assuming
2490correct multicast setup for these hosts).
2491@item
2492mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see
2493@url{http://user-mode-linux.sf.net}.
2494@item
2495Use @option{fd=h} to specify an already opened UDP multicast socket.
2496@end enumerate
2497
2498Example:
2499@example
2500# launch one QEMU instance
Stefan Weil3804da92012-05-11 22:21:50 +02002501qemu-system-i386 linux.img \
Thomas Huthabbbb032018-03-12 13:20:50 +01002502 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
2503 -netdev socket,id=n1,mcast=230.0.0.1:1234
blueswir15824d652009-03-28 06:44:27 +00002504# launch another QEMU instance on same "bus"
Stefan Weil3804da92012-05-11 22:21:50 +02002505qemu-system-i386 linux.img \
Thomas Huthabbbb032018-03-12 13:20:50 +01002506 -device e1000,netdev=n2,mac=52:54:00:12:34:57 \
2507 -netdev socket,id=n2,mcast=230.0.0.1:1234
blueswir15824d652009-03-28 06:44:27 +00002508# launch yet another QEMU instance on same "bus"
Stefan Weil3804da92012-05-11 22:21:50 +02002509qemu-system-i386 linux.img \
Thomas Huth37a44422018-08-13 13:51:44 +02002510 -device e1000,netdev=n3,mac=52:54:00:12:34:58 \
Thomas Huthabbbb032018-03-12 13:20:50 +01002511 -netdev socket,id=n3,mcast=230.0.0.1:1234
blueswir15824d652009-03-28 06:44:27 +00002512@end example
2513
2514Example (User Mode Linux compat.):
2515@example
Thomas Huthabbbb032018-03-12 13:20:50 +01002516# launch QEMU instance (note mcast address selected is UML's default)
Stefan Weil3804da92012-05-11 22:21:50 +02002517qemu-system-i386 linux.img \
Thomas Huthabbbb032018-03-12 13:20:50 +01002518 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
2519 -netdev socket,id=n1,mcast=239.192.168.1:1102
blueswir15824d652009-03-28 06:44:27 +00002520# launch UML
2521/path/to/linux ubd0=/path/to/root_fs eth0=mcast
2522@end example
2523
Mike Ryan3a75e742010-12-01 11:16:47 -08002524Example (send packets from host's 1.2.3.4):
2525@example
Stefan Weil3804da92012-05-11 22:21:50 +02002526qemu-system-i386 linux.img \
Thomas Huthabbbb032018-03-12 13:20:50 +01002527 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
2528 -netdev socket,id=n1,mcast=239.192.168.1:1102,localaddr=1.2.3.4
Mike Ryan3a75e742010-12-01 11:16:47 -08002529@end example
2530
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01002531@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 +01002532Configure a L2TPv3 pseudowire host network backend. L2TPv3 (RFC3391) is a
2533popular protocol to transport Ethernet (and other Layer 2) data frames between
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01002534two systems. It is present in routers, firewalls and the Linux kernel
2535(from version 3.3 onwards).
2536
2537This transport allows a VM to communicate to another VM, router or firewall directly.
2538
Markus Armbruster1e9a7372017-10-02 16:03:01 +02002539@table @option
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01002540@item src=@var{srcaddr}
2541 source address (mandatory)
2542@item dst=@var{dstaddr}
2543 destination address (mandatory)
2544@item udp
2545 select udp encapsulation (default is ip).
2546@item srcport=@var{srcport}
2547 source udp port.
2548@item dstport=@var{dstport}
2549 destination udp port.
2550@item ipv6
2551 force v6, otherwise defaults to v4.
2552@item rxcookie=@var{rxcookie}
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02002553@itemx txcookie=@var{txcookie}
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01002554 Cookies are a weak form of security in the l2tpv3 specification.
2555Their function is mostly to prevent misconfiguration. By default they are 32
2556bit.
2557@item cookie64
2558 Set cookie size to 64 bit instead of the default 32
2559@item counter=off
2560 Force a 'cut-down' L2TPv3 with no counter as in
2561draft-mkonstan-l2tpext-keyed-ipv6-tunnel-00
2562@item pincounter=on
2563 Work around broken counter handling in peer. This may also help on
2564networks which have packet reorder.
2565@item offset=@var{offset}
2566 Add an extra offset between header and data
Markus Armbruster1e9a7372017-10-02 16:03:01 +02002567@end table
Anton Ivanov3fb69aa2014-06-20 10:34:41 +01002568
2569For example, to attach a VM running on host 4.3.2.1 via L2TPv3 to the bridge br-lan
2570on the remote Linux host 1.2.3.4:
2571@example
2572# Setup tunnel on linux host using raw ip as encapsulation
2573# on 1.2.3.4
2574ip l2tp add tunnel remote 4.3.2.1 local 1.2.3.4 tunnel_id 1 peer_tunnel_id 1 \
2575 encap udp udp_sport 16384 udp_dport 16384
2576ip l2tp add session tunnel_id 1 name vmtunnel0 session_id \
2577 0xFFFFFFFF peer_session_id 0xFFFFFFFF
2578ifconfig vmtunnel0 mtu 1500
2579ifconfig vmtunnel0 up
2580brctl addif br-lan vmtunnel0
2581
2582
2583# on 4.3.2.1
2584# launch QEMU instance - if your network has reorder or is very lossy add ,pincounter
2585
Thomas Huthabbbb032018-03-12 13:20:50 +01002586qemu-system-i386 linux.img -device e1000,netdev=n1 \
2587 -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 +01002588
2589@end example
2590
Stefan Hajnoczi08d12022012-08-14 14:14:27 +01002591@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 +01002592Configure VDE backend to connect to PORT @var{n} of a vde switch running on host and
blueswir15824d652009-03-28 06:44:27 +00002593listening for incoming connections on @var{socketpath}. Use GROUP @var{groupname}
2594and MODE @var{octalmode} to change default ownership and permissions for
Stefan Weilc1ba4e02011-09-05 18:13:03 +02002595communication port. This option is only available if QEMU has been compiled
blueswir15824d652009-03-28 06:44:27 +00002596with vde support enabled.
2597
2598Example:
2599@example
2600# launch vde switch
2601vde_switch -F -sock /tmp/myswitch
2602# launch QEMU instance
Thomas Huthabbbb032018-03-12 13:20:50 +01002603qemu-system-i386 linux.img -nic vde,sock=/tmp/myswitch
blueswir15824d652009-03-28 06:44:27 +00002604@end example
2605
Changchun Ouyangb931bfb2015-09-23 12:20:00 +08002606@item -netdev vhost-user,chardev=@var{id}[,vhostforce=on|off][,queues=n]
Nikolay Nikolaev03ce5742014-06-10 13:02:16 +03002607
2608Establish a vhost-user netdev, backed by a chardev @var{id}. The chardev should
2609be a unix domain socket backed one. The vhost-user uses a specifically defined
2610protocol to pass vhost ioctl replacement messages to an application on the other
2611end of the socket. On non-MSIX guests, the feature can be forced with
Changchun Ouyangb931bfb2015-09-23 12:20:00 +08002612@var{vhostforce}. Use 'queues=@var{n}' to specify the number of queues to
2613be created for multiqueue vhost-user.
Nikolay Nikolaev03ce5742014-06-10 13:02:16 +03002614
2615Example:
2616@example
2617qemu -m 512 -object memory-backend-file,id=mem,size=512M,mem-path=/hugetlbfs,share=on \
2618 -numa node,memdev=mem \
Vincenzo Maffione79cad2f2017-02-20 17:45:09 +01002619 -chardev socket,id=chr0,path=/path/to/socket \
Nikolay Nikolaev03ce5742014-06-10 13:02:16 +03002620 -netdev type=vhost-user,id=net0,chardev=chr0 \
2621 -device virtio-net-pci,netdev=net0
2622@end example
2623
Thomas Huthabbbb032018-03-12 13:20:50 +01002624@item -netdev hubport,id=@var{id},hubid=@var{hubid}[,netdev=@var{nd}]
Thomas Huth78cd6f72018-02-21 11:18:36 +01002625
Thomas Huthabbbb032018-03-12 13:20:50 +01002626Create a hub port on the emulated hub with ID @var{hubid}.
Thomas Huth78cd6f72018-02-21 11:18:36 +01002627
Thomas Huthabbbb032018-03-12 13:20:50 +01002628The hubport netdev lets you connect a NIC to a QEMU emulated hub instead of a
Thomas Huthaf1a5c32018-04-30 20:02:23 +02002629single netdev. Alternatively, you can also connect the hubport to another
2630netdev with ID @var{nd} by using the @option{netdev=@var{nd}} option.
Thomas Huthabbbb032018-03-12 13:20:50 +01002631
Thomas Huthaf1a5c32018-04-30 20:02:23 +02002632@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 +01002633@findex -net
2634Legacy option to configure or create an on-board (or machine default) Network
Thomas Huthaf1a5c32018-04-30 20:02:23 +02002635Interface Card(NIC) and connect it either to the emulated hub with ID 0 (i.e.
2636the default hub), or to the netdev @var{nd}.
Thomas Huthabbbb032018-03-12 13:20:50 +01002637The NIC is an e1000 by default on the PC target. Optionally, the MAC address
2638can be changed to @var{mac}, the device address set to @var{addr} (PCI cards
2639only), and a @var{name} can be assigned for use in monitor commands.
2640Optionally, for PCI cards, you can specify the number @var{v} of MSI-X vectors
2641that the card should have; this option currently only affects virtio cards; set
2642@var{v} = 0 to disable MSI-X. If no @option{-net} option is specified, a single
2643NIC is created. QEMU can emulate several different models of network card.
2644Use @code{-net nic,model=help} for a list of available devices for your target.
2645
Thomas Huthaf1a5c32018-04-30 20:02:23 +02002646@item -net user|tap|bridge|socket|l2tpv3|vde[,...][,name=@var{name}]
Thomas Huthabbbb032018-03-12 13:20:50 +01002647Configure a host network backend (with the options corresponding to the same
Thomas Huthaf1a5c32018-04-30 20:02:23 +02002648@option{-netdev} option) and connect it to the emulated hub 0 (the default
2649hub). Use @var{name} to specify the name of the hub port.
blueswir15824d652009-03-28 06:44:27 +00002650ETEXI
2651
Markus Armbrusterc70a01e2013-02-13 19:49:40 +01002652STEXI
2653@end table
2654ETEXI
Matthew Booth7273a2d2009-10-30 13:41:12 +00002655DEFHEADING()
2656
Markus Armbrusterde6b4f92017-10-02 16:03:00 +02002657DEFHEADING(Character device options:)
Matthew Booth7273a2d2009-10-30 13:41:12 +00002658
2659DEF("chardev", HAS_ARG, QEMU_OPTION_chardev,
Lin Ma517b3d42016-08-17 01:13:52 +08002660 "-chardev help\n"
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002661 "-chardev null,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
Corey Minyard5dd1f022014-10-02 11:17:37 -05002662 "-chardev socket,id=id[,host=host],port=port[,to=to][,ipv4][,ipv6][,nodelay][,reconnect=seconds]\n"
Julia Suvorova981b06e2018-10-19 01:35:00 +03002663 " [,server][,nowait][,telnet][,websocket][,reconnect=seconds][,mux=on|off]\n"
Daniel P. Berrangefd4a5fd2019-03-08 15:21:50 +00002664 " [,logfile=PATH][,logappend=on|off][,tls-creds=ID][,tls-authz=ID] (tcp)\n"
Julia Suvorova981b06e2018-10-19 01:35:00 +03002665 "-chardev socket,id=id,path=path[,server][,nowait][,telnet][,websocket][,reconnect=seconds]\n"
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002666 " [,mux=on|off][,logfile=PATH][,logappend=on|off] (unix)\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00002667 "-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr]\n"
Jan Kiszka97331282010-04-06 16:55:54 +02002668 " [,localport=localport][,ipv4][,ipv6][,mux=on|off]\n"
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002669 " [,logfile=PATH][,logappend=on|off]\n"
2670 "-chardev msmouse,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00002671 "-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]\n"
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002672 " [,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2673 "-chardev ringbuf,id=id[,size=size][,logfile=PATH][,logappend=on|off]\n"
2674 "-chardev file,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2675 "-chardev pipe,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00002676#ifdef _WIN32
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002677 "-chardev console,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2678 "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00002679#else
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002680 "-chardev pty,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2681 "-chardev stdio,id=id[,mux=on|off][,signal=on|off][,logfile=PATH][,logappend=on|off]\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00002682#endif
2683#ifdef CONFIG_BRLAPI
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002684 "-chardev braille,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00002685#endif
2686#if defined(__linux__) || defined(__sun__) || defined(__FreeBSD__) \
2687 || defined(__NetBSD__) || defined(__OpenBSD__) || defined(__DragonFly__)
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002688 "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2689 "-chardev tty,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00002690#endif
2691#if defined(__linux__) || defined(__FreeBSD__) || defined(__DragonFly__)
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002692 "-chardev parallel,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
2693 "-chardev parport,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
Matthew Booth7273a2d2009-10-30 13:41:12 +00002694#endif
Alon Levycbcc6332011-01-19 10:49:50 +02002695#if defined(CONFIG_SPICE)
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002696 "-chardev spicevmc,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n"
2697 "-chardev spiceport,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n"
Alon Levycbcc6332011-01-19 10:49:50 +02002698#endif
Blue Swirlad960902010-03-29 19:23:52 +00002699 , QEMU_ARCH_ALL
Matthew Booth7273a2d2009-10-30 13:41:12 +00002700)
2701
2702STEXI
Markus Armbrusterdddba062017-10-02 16:03:06 +02002703
2704The general form of a character device option is:
2705@table @option
Thomas Huth16fdc562018-01-30 10:36:21 +01002706@item -chardev @var{backend},id=@var{id}[,mux=on|off][,@var{options}]
Stefan Weil6616b2a2010-02-05 23:52:05 +01002707@findex -chardev
Matthew Booth7273a2d2009-10-30 13:41:12 +00002708Backend is one of:
2709@option{null},
2710@option{socket},
2711@option{udp},
2712@option{msmouse},
2713@option{vc},
Markus Armbruster4f573782013-07-26 16:44:32 +02002714@option{ringbuf},
Matthew Booth7273a2d2009-10-30 13:41:12 +00002715@option{file},
2716@option{pipe},
2717@option{console},
2718@option{serial},
2719@option{pty},
2720@option{stdio},
2721@option{braille},
2722@option{tty},
Gerd Hoffmann88a946d2013-01-10 14:20:58 +01002723@option{parallel},
Alon Levycbcc6332011-01-19 10:49:50 +02002724@option{parport},
Thomas Huth16fdc562018-01-30 10:36:21 +01002725@option{spicevmc},
Marc-André Lureau5a49d3e2012-12-05 16:15:34 +01002726@option{spiceport}.
Matthew Booth7273a2d2009-10-30 13:41:12 +00002727The specific backend will determine the applicable options.
2728
Markus Armbrusterdddba062017-10-02 16:03:06 +02002729Use @code{-chardev help} to print all available chardev backend types.
Lin Ma517b3d42016-08-17 01:13:52 +08002730
Matthew Booth7273a2d2009-10-30 13:41:12 +00002731All devices must have an id, which can be any string up to 127 characters long.
2732It is used to uniquely identify this device in other command line directives.
2733
Jan Kiszka97331282010-04-06 16:55:54 +02002734A character device may be used in multiplexing mode by multiple front-ends.
Peter Maydella40db1b2016-02-16 17:28:58 +00002735Specify @option{mux=on} to enable this mode.
2736A multiplexer is a "1:N" device, and here the "1" end is your specified chardev
2737backend, and the "N" end is the various parts of QEMU that can talk to a chardev.
2738If you create a chardev with @option{id=myid} and @option{mux=on}, QEMU will
2739create a multiplexer with your specified ID, and you can then configure multiple
2740front ends to use that chardev ID for their input/output. Up to four different
2741front ends can be connected to a single multiplexed chardev. (Without
2742multiplexing enabled, a chardev can only be used by a single front end.)
2743For instance you could use this to allow a single stdio chardev to be used by
2744two serial ports and the QEMU monitor:
2745
2746@example
2747-chardev stdio,mux=on,id=char0 \
Marc-André Lureaubdbcb542016-10-11 21:41:21 +04002748-mon chardev=char0,mode=readline \
Peter Maydella40db1b2016-02-16 17:28:58 +00002749-serial chardev:char0 \
2750-serial chardev:char0
2751@end example
2752
2753You can have more than one multiplexer in a system configuration; for instance
2754you could have a TCP port multiplexed between UART 0 and UART 1, and stdio
2755multiplexed between the QEMU monitor and a parallel port:
2756
2757@example
2758-chardev stdio,mux=on,id=char0 \
Marc-André Lureaubdbcb542016-10-11 21:41:21 +04002759-mon chardev=char0,mode=readline \
Peter Maydella40db1b2016-02-16 17:28:58 +00002760-parallel chardev:char0 \
2761-chardev tcp,...,mux=on,id=char1 \
2762-serial chardev:char1 \
2763-serial chardev:char1
2764@end example
2765
2766When you're using a multiplexed character device, some escape sequences are
2767interpreted in the input. @xref{mux_keys, Keys in the character backend
2768multiplexer}.
2769
2770Note that some other command line options may implicitly create multiplexed
2771character backends; for instance @option{-serial mon:stdio} creates a
2772multiplexed stdio backend connected to the serial port and the QEMU monitor,
2773and @option{-nographic} also multiplexes the console and the monitor to
2774stdio.
2775
2776There is currently no support for multiplexing in the other direction
2777(where a single QEMU front end takes input and output from multiple chardevs).
Jan Kiszka97331282010-04-06 16:55:54 +02002778
Daniel P. Berranged0d77082016-01-11 12:44:41 +00002779Every backend supports the @option{logfile} option, which supplies the path
2780to a file to record all data transmitted via the backend. The @option{logappend}
2781option controls whether the log file will be truncated or appended to when
2782opened.
2783
Markus Armbrusterdddba062017-10-02 16:03:06 +02002784@end table
Matthew Booth7273a2d2009-10-30 13:41:12 +00002785
Markus Armbrusterdddba062017-10-02 16:03:06 +02002786The available backends are:
2787
2788@table @option
Thomas Huth16fdc562018-01-30 10:36:21 +01002789@item -chardev null,id=@var{id}
Matthew Booth7273a2d2009-10-30 13:41:12 +00002790A void device. This device will not emit any data, and will drop any data it
2791receives. The null backend does not take any options.
2792
Daniel P. Berrangefd4a5fd2019-03-08 15:21:50 +00002793@item -chardev socket,id=@var{id}[,@var{TCP options} or @var{unix options}][,server][,nowait][,telnet][,websocket][,reconnect=@var{seconds}][,tls-creds=@var{id}][,tls-authz=@var{id}]
Matthew Booth7273a2d2009-10-30 13:41:12 +00002794
2795Create a two-way stream socket, which can be either a TCP or a unix socket. A
2796unix socket will be created if @option{path} is specified. Behaviour is
2797undefined if TCP options are specified for a unix socket.
2798
2799@option{server} specifies that the socket shall be a listening socket.
2800
2801@option{nowait} specifies that QEMU should not block waiting for a client to
2802connect to a listening socket.
2803
2804@option{telnet} specifies that traffic on the socket should interpret telnet
2805escape sequences.
2806
Julia Suvorova981b06e2018-10-19 01:35:00 +03002807@option{websocket} specifies that the socket uses WebSocket protocol for
2808communication.
2809
Corey Minyard5dd1f022014-10-02 11:17:37 -05002810@option{reconnect} sets the timeout for reconnecting on non-server sockets when
2811the remote end goes away. qemu will delay this many seconds and then attempt
2812to reconnect. Zero disables reconnecting, and is the default.
2813
Daniel P. Berrangea8fb5422016-01-19 11:14:31 +00002814@option{tls-creds} requests enablement of the TLS protocol for encryption,
2815and specifies the id of the TLS credentials to use for the handshake. The
2816credentials must be previously created with the @option{-object tls-creds}
2817argument.
2818
Daniel P. Berrangefd4a5fd2019-03-08 15:21:50 +00002819@option{tls-auth} provides the ID of the QAuthZ authorization object against
2820which the client's x509 distinguished name will be validated. This object is
2821only resolved at time of use, so can be deleted and recreated on the fly
2822while the chardev server is active. If missing, it will default to denying
2823access.
2824
Matthew Booth7273a2d2009-10-30 13:41:12 +00002825TCP and unix socket options are given below:
2826
2827@table @option
2828
Thomas Huth16fdc562018-01-30 10:36:21 +01002829@item TCP options: port=@var{port}[,host=@var{host}][,to=@var{to}][,ipv4][,ipv6][,nodelay]
Matthew Booth7273a2d2009-10-30 13:41:12 +00002830
2831@option{host} for a listening socket specifies the local address to be bound.
2832For a connecting socket species the remote host to connect to. @option{host} is
2833optional for listening sockets. If not specified it defaults to @code{0.0.0.0}.
2834
2835@option{port} for a listening socket specifies the local port to be bound. For a
2836connecting socket specifies the port on the remote host to connect to.
2837@option{port} can be given as either a port number or a service name.
2838@option{port} is required.
2839
2840@option{to} is only relevant to listening sockets. If it is specified, and
2841@option{port} cannot be bound, QEMU will attempt to bind to subsequent ports up
2842to and including @option{to} until it succeeds. @option{to} must be specified
2843as a port number.
2844
2845@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
2846If neither is specified the socket may use either protocol.
2847
2848@option{nodelay} disables the Nagle algorithm.
2849
2850@item unix options: path=@var{path}
2851
2852@option{path} specifies the local path of the unix socket. @option{path} is
2853required.
2854
2855@end table
2856
Thomas Huth16fdc562018-01-30 10:36:21 +01002857@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 +00002858
2859Sends all traffic from the guest to a remote host over UDP.
2860
2861@option{host} specifies the remote host to connect to. If not specified it
2862defaults to @code{localhost}.
2863
2864@option{port} specifies the port on the remote host to connect to. @option{port}
2865is required.
2866
2867@option{localaddr} specifies the local address to bind to. If not specified it
2868defaults to @code{0.0.0.0}.
2869
2870@option{localport} specifies the local port to bind to. If not specified any
2871available local port will be used.
2872
2873@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
2874If neither is specified the device may use either protocol.
2875
Thomas Huth16fdc562018-01-30 10:36:21 +01002876@item -chardev msmouse,id=@var{id}
Matthew Booth7273a2d2009-10-30 13:41:12 +00002877
2878Forward QEMU's emulated msmouse events to the guest. @option{msmouse} does not
2879take any options.
2880
Thomas Huth16fdc562018-01-30 10:36:21 +01002881@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 +00002882
2883Connect to a QEMU text console. @option{vc} may optionally be given a specific
2884size.
2885
2886@option{width} and @option{height} specify the width and height respectively of
2887the console, in pixels.
2888
2889@option{cols} and @option{rows} specify that the console be sized to fit a text
2890console with the given dimensions.
2891
Thomas Huth16fdc562018-01-30 10:36:21 +01002892@item -chardev ringbuf,id=@var{id}[,size=@var{size}]
Lei Li51767e72013-01-25 00:03:19 +08002893
Markus Armbruster3949e592013-02-06 21:27:24 +01002894Create a ring buffer with fixed size @option{size}.
Stefan Hajnoczie69f7d22016-09-19 11:56:26 +01002895@var{size} must be a power of two and defaults to @code{64K}.
Lei Li51767e72013-01-25 00:03:19 +08002896
Thomas Huth16fdc562018-01-30 10:36:21 +01002897@item -chardev file,id=@var{id},path=@var{path}
Matthew Booth7273a2d2009-10-30 13:41:12 +00002898
2899Log all traffic received from the guest to a file.
2900
2901@option{path} specifies the path of the file to be opened. This file will be
2902created if it does not already exist, and overwritten if it does. @option{path}
2903is required.
2904
Thomas Huth16fdc562018-01-30 10:36:21 +01002905@item -chardev pipe,id=@var{id},path=@var{path}
Matthew Booth7273a2d2009-10-30 13:41:12 +00002906
2907Create a two-way connection to the guest. The behaviour differs slightly between
2908Windows hosts and other hosts:
2909
2910On Windows, a single duplex pipe will be created at
2911@file{\\.pipe\@option{path}}.
2912
2913On other hosts, 2 pipes will be created called @file{@option{path}.in} and
2914@file{@option{path}.out}. Data written to @file{@option{path}.in} will be
2915received by the guest. Data written by the guest can be read from
2916@file{@option{path}.out}. QEMU will not create these fifos, and requires them to
2917be present.
2918
2919@option{path} forms part of the pipe path as described above. @option{path} is
2920required.
2921
Thomas Huth16fdc562018-01-30 10:36:21 +01002922@item -chardev console,id=@var{id}
Matthew Booth7273a2d2009-10-30 13:41:12 +00002923
2924Send traffic from the guest to QEMU's standard output. @option{console} does not
2925take any options.
2926
2927@option{console} is only available on Windows hosts.
2928
Thomas Huth16fdc562018-01-30 10:36:21 +01002929@item -chardev serial,id=@var{id},path=@option{path}
Matthew Booth7273a2d2009-10-30 13:41:12 +00002930
2931Send traffic from the guest to a serial device on the host.
2932
Gerd Hoffmannd59044e2012-12-19 13:50:29 +01002933On Unix hosts serial will actually accept any tty device,
2934not only serial lines.
Matthew Booth7273a2d2009-10-30 13:41:12 +00002935
2936@option{path} specifies the name of the serial device to open.
2937
Thomas Huth16fdc562018-01-30 10:36:21 +01002938@item -chardev pty,id=@var{id}
Matthew Booth7273a2d2009-10-30 13:41:12 +00002939
2940Create a new pseudo-terminal on the host and connect to it. @option{pty} does
2941not take any options.
2942
2943@option{pty} is not available on Windows hosts.
2944
Thomas Huth16fdc562018-01-30 10:36:21 +01002945@item -chardev stdio,id=@var{id}[,signal=on|off]
Stefan Weilb65ee4f2012-05-11 22:25:50 +02002946Connect to standard input and standard output of the QEMU process.
Aurelien Jarnob7fdb3a2010-07-13 21:13:12 +02002947
2948@option{signal} controls if signals are enabled on the terminal, that includes
2949exiting QEMU with the key sequence @key{Control-c}. This option is enabled by
2950default, use @option{signal=off} to disable it.
2951
Thomas Huth16fdc562018-01-30 10:36:21 +01002952@item -chardev braille,id=@var{id}
Matthew Booth7273a2d2009-10-30 13:41:12 +00002953
2954Connect to a local BrlAPI server. @option{braille} does not take any options.
2955
Thomas Huth16fdc562018-01-30 10:36:21 +01002956@item -chardev tty,id=@var{id},path=@var{path}
Matthew Booth7273a2d2009-10-30 13:41:12 +00002957
Matthew Booth7273a2d2009-10-30 13:41:12 +00002958@option{tty} is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD and
Markus Armbrusterd037d6b2013-02-13 15:54:15 +01002959DragonFlyBSD hosts. It is an alias for @option{serial}.
Matthew Booth7273a2d2009-10-30 13:41:12 +00002960
2961@option{path} specifies the path to the tty. @option{path} is required.
2962
Thomas Huth16fdc562018-01-30 10:36:21 +01002963@item -chardev parallel,id=@var{id},path=@var{path}
2964@itemx -chardev parport,id=@var{id},path=@var{path}
Matthew Booth7273a2d2009-10-30 13:41:12 +00002965
Gerd Hoffmann88a946d2013-01-10 14:20:58 +01002966@option{parallel} is only available on Linux, FreeBSD and DragonFlyBSD hosts.
Matthew Booth7273a2d2009-10-30 13:41:12 +00002967
2968Connect to a local parallel port.
2969
2970@option{path} specifies the path to the parallel port device. @option{path} is
2971required.
2972
Thomas Huth16fdc562018-01-30 10:36:21 +01002973@item -chardev spicevmc,id=@var{id},debug=@var{debug},name=@var{name}
Alon Levycbcc6332011-01-19 10:49:50 +02002974
Stefan Hajnoczi3a846902011-10-06 11:24:12 +01002975@option{spicevmc} is only available when spice support is built in.
2976
Alon Levycbcc6332011-01-19 10:49:50 +02002977@option{debug} debug level for spicevmc
2978
2979@option{name} name of spice channel to connect to
2980
2981Connect to a spice virtual machine channel, such as vdiport.
Alon Levycbcc6332011-01-19 10:49:50 +02002982
Thomas Huth16fdc562018-01-30 10:36:21 +01002983@item -chardev spiceport,id=@var{id},debug=@var{debug},name=@var{name}
Marc-André Lureau5a49d3e2012-12-05 16:15:34 +01002984
2985@option{spiceport} is only available when spice support is built in.
2986
2987@option{debug} debug level for spicevmc
2988
2989@option{name} name of spice port to connect to
2990
2991Connect to a spice port, allowing a Spice client to handle the traffic
2992identified by a name (preferably a fqdn).
Matthew Booth7273a2d2009-10-30 13:41:12 +00002993ETEXI
2994
Markus Armbrusterc70a01e2013-02-13 19:49:40 +01002995STEXI
2996@end table
2997ETEXI
Matthew Booth7273a2d2009-10-30 13:41:12 +00002998DEFHEADING()
2999
Markus Armbrusterde6b4f92017-10-02 16:03:00 +02003000DEFHEADING(Bluetooth(R) options:)
Markus Armbrusterc70a01e2013-02-13 19:49:40 +01003001STEXI
3002@table @option
3003ETEXI
Matthew Booth7273a2d2009-10-30 13:41:12 +00003004
blueswir15824d652009-03-28 06:44:27 +00003005DEF("bt", HAS_ARG, QEMU_OPTION_bt, \
blueswir15824d652009-03-28 06:44:27 +00003006 "-bt hci,null dumb bluetooth HCI - doesn't respond to commands\n" \
3007 "-bt hci,host[:id]\n" \
3008 " use host's HCI with the given name\n" \
3009 "-bt hci[,vlan=n]\n" \
3010 " emulate a standard HCI in virtual scatternet 'n'\n" \
3011 "-bt vhci[,vlan=n]\n" \
3012 " add host computer to virtual scatternet 'n' using VHCI\n" \
3013 "-bt device:dev[,vlan=n]\n" \
Blue Swirlad960902010-03-29 19:23:52 +00003014 " emulate a bluetooth device 'dev' in scatternet 'n'\n",
3015 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003016STEXI
blueswir15824d652009-03-28 06:44:27 +00003017@item -bt hci[...]
Stefan Weil6616b2a2010-02-05 23:52:05 +01003018@findex -bt
blueswir15824d652009-03-28 06:44:27 +00003019Defines the function of the corresponding Bluetooth HCI. -bt options
3020are matched with the HCIs present in the chosen machine type. For
3021example when emulating a machine with only one HCI built into it, only
3022the first @code{-bt hci[...]} option is valid and defines the HCI's
3023logic. The Transport Layer is decided by the machine type. Currently
3024the machines @code{n800} and @code{n810} have one HCI and all other
3025machines have none.
3026
Thomas Huthc0188e62018-11-12 11:00:30 +01003027Note: This option and the whole bluetooth subsystem is considered as deprecated.
3028If you still use it, please send a mail to @email{qemu-devel@@nongnu.org} where
3029you describe your usecase.
3030
blueswir15824d652009-03-28 06:44:27 +00003031@anchor{bt-hcis}
3032The following three types are recognized:
3033
Kevin Wolfb3f046c2009-10-09 10:58:35 +02003034@table @option
blueswir15824d652009-03-28 06:44:27 +00003035@item -bt hci,null
3036(default) The corresponding Bluetooth HCI assumes no internal logic
3037and will not respond to any HCI commands or emit events.
3038
3039@item -bt hci,host[:@var{id}]
3040(@code{bluez} only) The corresponding HCI passes commands / events
3041to / from the physical HCI identified by the name @var{id} (default:
3042@code{hci0}) on the computer running QEMU. Only available on @code{bluez}
3043capable systems like Linux.
3044
3045@item -bt hci[,vlan=@var{n}]
3046Add a virtual, standard HCI that will participate in the Bluetooth
3047scatternet @var{n} (default @code{0}). Similarly to @option{-net}
3048VLANs, devices inside a bluetooth network @var{n} can only communicate
3049with other devices in the same network (scatternet).
3050@end table
3051
3052@item -bt vhci[,vlan=@var{n}]
3053(Linux-host only) Create a HCI in scatternet @var{n} (default 0) attached
3054to the host bluetooth stack instead of to the emulated target. This
3055allows the host and target machines to participate in a common scatternet
3056and communicate. Requires the Linux @code{vhci} driver installed. Can
3057be used as following:
3058
3059@example
Stefan Weil3804da92012-05-11 22:21:50 +02003060qemu-system-i386 [...OPTIONS...] -bt hci,vlan=5 -bt vhci,vlan=5
blueswir15824d652009-03-28 06:44:27 +00003061@end example
3062
3063@item -bt device:@var{dev}[,vlan=@var{n}]
3064Emulate a bluetooth device @var{dev} and place it in network @var{n}
3065(default @code{0}). QEMU can only emulate one type of bluetooth devices
3066currently:
3067
Kevin Wolfb3f046c2009-10-09 10:58:35 +02003068@table @option
blueswir15824d652009-03-28 06:44:27 +00003069@item keyboard
3070Virtual wireless keyboard implementing the HIDP bluetooth profile.
3071@end table
blueswir15824d652009-03-28 06:44:27 +00003072ETEXI
3073
Markus Armbrusterc70a01e2013-02-13 19:49:40 +01003074STEXI
3075@end table
3076ETEXI
blueswir15824d652009-03-28 06:44:27 +00003077DEFHEADING()
3078
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05003079#ifdef CONFIG_TPM
Markus Armbrusterde6b4f92017-10-02 16:03:00 +02003080DEFHEADING(TPM device options:)
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05003081
3082DEF("tpmdev", HAS_ARG, QEMU_OPTION_tpmdev, \
Stefan Berger92dcc232013-02-27 12:47:54 -05003083 "-tpmdev passthrough,id=id[,path=path][,cancel-path=path]\n"
3084 " use path to provide path to a character device; default is /dev/tpm0\n"
3085 " use cancel-path to provide path to TPM's cancel sysfs entry; if\n"
Amarnath Vallurif4ede812017-09-29 14:10:20 +03003086 " not provided it will be searched for in /sys/class/misc/tpm?/device\n"
3087 "-tpmdev emulator,id=id,chardev=dev\n"
3088 " configure the TPM device using chardev backend\n",
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05003089 QEMU_ARCH_ALL)
3090STEXI
3091
3092The general form of a TPM device option is:
3093@table @option
3094
Thomas Huth16fdc562018-01-30 10:36:21 +01003095@item -tpmdev @var{backend},id=@var{id}[,@var{options}]
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05003096@findex -tpmdev
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05003097
3098The specific backend type will determine the applicable options.
Corey Bryant28c4fa32013-03-20 12:34:49 -04003099The @code{-tpmdev} option creates the TPM backend and requires a
3100@code{-device} option that specifies the TPM frontend interface model.
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05003101
Markus Armbruster2252aaf2017-10-02 16:03:05 +02003102Use @code{-tpmdev help} to print all available TPM backend types.
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05003103
Markus Armbruster2252aaf2017-10-02 16:03:05 +02003104@end table
3105
3106The available backends are:
3107
3108@table @option
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05003109
Thomas Huth16fdc562018-01-30 10:36:21 +01003110@item -tpmdev passthrough,id=@var{id},path=@var{path},cancel-path=@var{cancel-path}
Stefan Berger4549a8b2013-02-27 12:47:53 -05003111
3112(Linux-host only) Enable access to the host's TPM using the passthrough
3113driver.
3114
3115@option{path} specifies the path to the host's TPM device, i.e., on
3116a Linux host this would be @code{/dev/tpm0}.
3117@option{path} is optional and by default @code{/dev/tpm0} is used.
3118
Stefan Berger92dcc232013-02-27 12:47:54 -05003119@option{cancel-path} specifies the path to the host TPM device's sysfs
3120entry allowing for cancellation of an ongoing TPM command.
3121@option{cancel-path} is optional and by default QEMU will search for the
3122sysfs entry to use.
3123
Stefan Berger4549a8b2013-02-27 12:47:53 -05003124Some notes about using the host's TPM with the passthrough driver:
3125
3126The TPM device accessed by the passthrough driver must not be
3127used by any other application on the host.
3128
3129Since the host's firmware (BIOS/UEFI) has already initialized the TPM,
3130the VM's firmware (BIOS/UEFI) will not be able to initialize the
3131TPM again and may therefore not show a TPM-specific menu that would
3132otherwise allow the user to configure the TPM, e.g., allow the user to
3133enable/disable or activate/deactivate the TPM.
3134Further, if TPM ownership is released from within a VM then the host's TPM
3135will get disabled and deactivated. To enable and activate the
3136TPM again afterwards, the host has to be rebooted and the user is
3137required to enter the firmware's menu to enable and activate the TPM.
3138If the TPM is left disabled and/or deactivated most TPM commands will fail.
3139
3140To create a passthrough TPM use the following two options:
3141@example
3142-tpmdev passthrough,id=tpm0 -device tpm-tis,tpmdev=tpm0
3143@end example
3144Note that the @code{-tpmdev} id is @code{tpm0} and is referenced by
3145@code{tpmdev=tpm0} in the device option.
3146
Thomas Huth16fdc562018-01-30 10:36:21 +01003147@item -tpmdev emulator,id=@var{id},chardev=@var{dev}
Amarnath Vallurif4ede812017-09-29 14:10:20 +03003148
3149(Linux-host only) Enable access to a TPM emulator using Unix domain socket based
3150chardev backend.
3151
3152@option{chardev} specifies the unique ID of a character device backend that provides connection to the software TPM server.
3153
3154To create a TPM emulator backend device with chardev socket backend:
3155@example
3156
3157-chardev socket,id=chrtpm,path=/tmp/swtpm-sock -tpmdev emulator,id=tpm0,chardev=chrtpm -device tpm-tis,tpmdev=tpm0
3158
3159@end example
3160
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05003161ETEXI
3162
Markus Armbruster2252aaf2017-10-02 16:03:05 +02003163STEXI
3164@end table
3165ETEXI
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05003166DEFHEADING()
3167
3168#endif
3169
Markus Armbrusterde6b4f92017-10-02 16:03:00 +02003170DEFHEADING(Linux/Multiboot boot specific:)
blueswir15824d652009-03-28 06:44:27 +00003171STEXI
Alexander Graf7677f052009-06-28 16:55:55 +02003172
3173When using these options, you can use a given Linux or Multiboot
3174kernel without installing it in the disk image. It can be useful
blueswir15824d652009-03-28 06:44:27 +00003175for easier testing of various kernels.
3176
3177@table @option
3178ETEXI
3179
3180DEF("kernel", HAS_ARG, QEMU_OPTION_kernel, \
Blue Swirlad960902010-03-29 19:23:52 +00003181 "-kernel bzImage use 'bzImage' as kernel image\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003182STEXI
3183@item -kernel @var{bzImage}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003184@findex -kernel
Alexander Graf7677f052009-06-28 16:55:55 +02003185Use @var{bzImage} as kernel image. The kernel can be either a Linux kernel
3186or in multiboot format.
blueswir15824d652009-03-28 06:44:27 +00003187ETEXI
3188
3189DEF("append", HAS_ARG, QEMU_OPTION_append, \
Blue Swirlad960902010-03-29 19:23:52 +00003190 "-append cmdline use 'cmdline' as kernel command line\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003191STEXI
3192@item -append @var{cmdline}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003193@findex -append
blueswir15824d652009-03-28 06:44:27 +00003194Use @var{cmdline} as kernel command line
3195ETEXI
3196
3197DEF("initrd", HAS_ARG, QEMU_OPTION_initrd, \
Blue Swirlad960902010-03-29 19:23:52 +00003198 "-initrd file use 'file' as initial ram disk\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003199STEXI
3200@item -initrd @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003201@findex -initrd
blueswir15824d652009-03-28 06:44:27 +00003202Use @var{file} as initial ram disk.
Alexander Graf7677f052009-06-28 16:55:55 +02003203
3204@item -initrd "@var{file1} arg=foo,@var{file2}"
3205
3206This syntax is only available with multiboot.
3207
3208Use @var{file1} and @var{file2} as modules and pass arg=foo as parameter to the
3209first module.
blueswir15824d652009-03-28 06:44:27 +00003210ETEXI
3211
Grant Likely412beee2012-03-02 11:56:38 +00003212DEF("dtb", HAS_ARG, QEMU_OPTION_dtb, \
Peter A. G. Crosthwaite379b5c72012-03-04 21:03:54 +10003213 "-dtb file use 'file' as device tree image\n", QEMU_ARCH_ALL)
Grant Likely412beee2012-03-02 11:56:38 +00003214STEXI
3215@item -dtb @var{file}
3216@findex -dtb
3217Use @var{file} as a device tree binary (dtb) image and pass it to the kernel
3218on boot.
3219ETEXI
3220
blueswir15824d652009-03-28 06:44:27 +00003221STEXI
3222@end table
3223ETEXI
blueswir15824d652009-03-28 06:44:27 +00003224DEFHEADING()
3225
Markus Armbrusterde6b4f92017-10-02 16:03:00 +02003226DEFHEADING(Debug/Expert options:)
blueswir15824d652009-03-28 06:44:27 +00003227STEXI
3228@table @option
3229ETEXI
3230
Gabriel L. Somlo81b2b812015-04-29 11:21:53 -04003231DEF("fw_cfg", HAS_ARG, QEMU_OPTION_fwcfg,
3232 "-fw_cfg [name=]<name>,file=<file>\n"
Markus Armbruster63d31452016-04-18 18:29:50 +02003233 " add named fw_cfg entry with contents from file\n"
Gabriel L. Somlo6407d762015-09-29 12:29:01 -04003234 "-fw_cfg [name=]<name>,string=<str>\n"
Markus Armbruster63d31452016-04-18 18:29:50 +02003235 " add named fw_cfg entry with contents from string\n",
Gabriel L. Somlo81b2b812015-04-29 11:21:53 -04003236 QEMU_ARCH_ALL)
3237STEXI
Markus Armbruster63d31452016-04-18 18:29:50 +02003238
Gabriel L. Somlo81b2b812015-04-29 11:21:53 -04003239@item -fw_cfg [name=]@var{name},file=@var{file}
3240@findex -fw_cfg
Markus Armbruster63d31452016-04-18 18:29:50 +02003241Add named fw_cfg entry with contents from file @var{file}.
Gabriel L. Somlo6407d762015-09-29 12:29:01 -04003242
3243@item -fw_cfg [name=]@var{name},string=@var{str}
Markus Armbruster63d31452016-04-18 18:29:50 +02003244Add named fw_cfg entry with contents from string @var{str}.
3245
3246The terminating NUL character of the contents of @var{str} will not be
3247included as part of the fw_cfg item data. To insert contents with
3248embedded NUL characters, you have to use the @var{file} parameter.
3249
3250The fw_cfg entries are passed by QEMU through to the guest.
3251
3252Example:
3253@example
3254 -fw_cfg name=opt/com.mycompany/blob,file=./my_blob.bin
3255@end example
3256creates an fw_cfg entry named opt/com.mycompany/blob with contents
3257from ./my_blob.bin.
3258
Gabriel L. Somlo81b2b812015-04-29 11:21:53 -04003259ETEXI
3260
blueswir15824d652009-03-28 06:44:27 +00003261DEF("serial", HAS_ARG, QEMU_OPTION_serial, \
Blue Swirlad960902010-03-29 19:23:52 +00003262 "-serial dev redirect the serial port to char device 'dev'\n",
3263 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003264STEXI
3265@item -serial @var{dev}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003266@findex -serial
blueswir15824d652009-03-28 06:44:27 +00003267Redirect the virtual serial port to host character device
3268@var{dev}. The default device is @code{vc} in graphical mode and
3269@code{stdio} in non graphical mode.
3270
3271This option can be used several times to simulate up to 4 serial
3272ports.
3273
3274Use @code{-serial none} to disable all serial ports.
3275
3276Available character devices are:
Kevin Wolfb3f046c2009-10-09 10:58:35 +02003277@table @option
Kevin Wolf4e257e52009-10-09 10:58:36 +02003278@item vc[:@var{W}x@var{H}]
blueswir15824d652009-03-28 06:44:27 +00003279Virtual console. Optionally, a width and height can be given in pixel with
3280@example
3281vc:800x600
3282@end example
3283It is also possible to specify width or height in characters:
3284@example
3285vc:80Cx24C
3286@end example
3287@item pty
3288[Linux only] Pseudo TTY (a new PTY is automatically allocated)
3289@item none
3290No device is allocated.
3291@item null
3292void device
Ingo van Lil88e020e2013-12-20 14:44:53 +01003293@item chardev:@var{id}
3294Use a named character device defined with the @code{-chardev} option.
blueswir15824d652009-03-28 06:44:27 +00003295@item /dev/XXX
3296[Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port
3297parameters are set according to the emulated ones.
3298@item /dev/parport@var{N}
3299[Linux only, parallel port only] Use host parallel port
3300@var{N}. Currently SPP and EPP parallel port features can be used.
3301@item file:@var{filename}
3302Write output to @var{filename}. No character can be read.
3303@item stdio
3304[Unix only] standard input/output
3305@item pipe:@var{filename}
3306name pipe @var{filename}
3307@item COM@var{n}
3308[Windows only] Use host serial port @var{n}
3309@item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}]
3310This implements UDP Net Console.
3311When @var{remote_host} or @var{src_ip} are not specified
3312they default to @code{0.0.0.0}.
3313When not using a specified @var{src_port} a random port is automatically chosen.
blueswir15824d652009-03-28 06:44:27 +00003314
3315If you just want a simple readonly console you can use @code{netcat} or
Stefan Weilb65ee4f2012-05-11 22:25:50 +02003316@code{nc}, by starting QEMU with: @code{-serial udp::4555} and nc as:
3317@code{nc -u -l -p 4555}. Any time QEMU writes something to that port it
blueswir15824d652009-03-28 06:44:27 +00003318will appear in the netconsole session.
3319
3320If you plan to send characters back via netconsole or you want to stop
Stefan Weilb65ee4f2012-05-11 22:25:50 +02003321and start QEMU a lot of times, you should have QEMU use the same
blueswir15824d652009-03-28 06:44:27 +00003322source port each time by using something like @code{-serial
Stefan Weilb65ee4f2012-05-11 22:25:50 +02003323udp::4555@@:4556} to QEMU. Another approach is to use a patched
blueswir15824d652009-03-28 06:44:27 +00003324version of netcat which can listen to a TCP port and send and receive
3325characters via udp. If you have a patched version of netcat which
3326activates telnet remote echo and single char transfer, then you can
Marc-André Lureaubd1caa32016-12-22 18:56:38 +04003327use the following options to set up a netcat redirector to allow
Stefan Weilb65ee4f2012-05-11 22:25:50 +02003328telnet on port 5555 to access the QEMU port.
blueswir15824d652009-03-28 06:44:27 +00003329@table @code
Stefan Weil071c9392012-04-07 09:23:36 +02003330@item QEMU Options:
blueswir15824d652009-03-28 06:44:27 +00003331-serial udp::4555@@:4556
3332@item netcat options:
3333-u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T
3334@item telnet options:
3335localhost 5555
3336@end table
3337
Corey Minyard5dd1f022014-10-02 11:17:37 -05003338@item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay][,reconnect=@var{seconds}]
blueswir15824d652009-03-28 06:44:27 +00003339The TCP Net Console has two modes of operation. It can send the serial
3340I/O to a location or wait for a connection from a location. By default
3341the TCP Net Console is sent to @var{host} at the @var{port}. If you use
3342the @var{server} option QEMU will wait for a client socket application
3343to connect to the port before continuing, unless the @code{nowait}
3344option was specified. The @code{nodelay} option disables the Nagle buffering
Corey Minyard5dd1f022014-10-02 11:17:37 -05003345algorithm. The @code{reconnect} option only applies if @var{noserver} is
3346set, if the connection goes down it will attempt to reconnect at the
3347given interval. If @var{host} is omitted, 0.0.0.0 is assumed. Only
blueswir15824d652009-03-28 06:44:27 +00003348one TCP connection at a time is accepted. You can use @code{telnet} to
3349connect to the corresponding character device.
3350@table @code
3351@item Example to send tcp console to 192.168.0.2 port 4444
3352-serial tcp:192.168.0.2:4444
3353@item Example to listen and wait on port 4444 for connection
3354-serial tcp::4444,server
3355@item Example to not wait and listen on ip 192.168.0.100 port 4444
3356-serial tcp:192.168.0.100:4444,server,nowait
3357@end table
3358
3359@item telnet:@var{host}:@var{port}[,server][,nowait][,nodelay]
3360The telnet protocol is used instead of raw tcp sockets. The options
3361work the same as if you had specified @code{-serial tcp}. The
3362difference is that the port acts like a telnet server or client using
3363telnet option negotiation. This will also allow you to send the
3364MAGIC_SYSRQ sequence if you use a telnet that supports sending the break
3365sequence. Typically in unix telnet you do it with Control-] and then
3366type "send break" followed by pressing the enter key.
3367
Julia Suvorova981b06e2018-10-19 01:35:00 +03003368@item websocket:@var{host}:@var{port},server[,nowait][,nodelay]
3369The WebSocket protocol is used instead of raw tcp socket. The port acts as
3370a WebSocket server. Client mode is not supported.
3371
Corey Minyard5dd1f022014-10-02 11:17:37 -05003372@item unix:@var{path}[,server][,nowait][,reconnect=@var{seconds}]
blueswir15824d652009-03-28 06:44:27 +00003373A unix domain socket is used instead of a tcp socket. The option works the
3374same as if you had specified @code{-serial tcp} except the unix domain socket
3375@var{path} is used for connections.
3376
3377@item mon:@var{dev_string}
3378This is a special option to allow the monitor to be multiplexed onto
3379another serial port. The monitor is accessed with key sequence of
Paolo Bonzini02c4bdf2013-07-03 20:29:45 +04003380@key{Control-a} and then pressing @key{c}.
blueswir15824d652009-03-28 06:44:27 +00003381@var{dev_string} should be any one of the serial devices specified
3382above. An example to multiplex the monitor onto a telnet server
3383listening on port 4444 would be:
3384@table @code
3385@item -serial mon:telnet::4444,server,nowait
3386@end table
Michael Tokarevbe022d62013-07-11 12:55:50 +04003387When the monitor is multiplexed to stdio in this way, Ctrl+C will not terminate
3388QEMU any more but will be passed to the guest instead.
blueswir15824d652009-03-28 06:44:27 +00003389
3390@item braille
3391Braille device. This will use BrlAPI to display the braille output on a real
3392or fake device.
3393
Kevin Wolfbe8b28a2009-10-09 10:58:37 +02003394@item msmouse
3395Three button serial mouse. Configure the guest to use Microsoft protocol.
blueswir15824d652009-03-28 06:44:27 +00003396@end table
3397ETEXI
3398
3399DEF("parallel", HAS_ARG, QEMU_OPTION_parallel, \
Blue Swirlad960902010-03-29 19:23:52 +00003400 "-parallel dev redirect the parallel port to char device 'dev'\n",
3401 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003402STEXI
3403@item -parallel @var{dev}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003404@findex -parallel
blueswir15824d652009-03-28 06:44:27 +00003405Redirect the virtual parallel port to host device @var{dev} (same
3406devices as the serial port). On Linux hosts, @file{/dev/parportN} can
3407be used to use hardware devices connected on the corresponding host
3408parallel port.
3409
3410This option can be used several times to simulate up to 3 parallel
3411ports.
3412
3413Use @code{-parallel none} to disable all parallel ports.
3414ETEXI
3415
3416DEF("monitor", HAS_ARG, QEMU_OPTION_monitor, \
Blue Swirlad960902010-03-29 19:23:52 +00003417 "-monitor dev redirect the monitor to char device 'dev'\n",
3418 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003419STEXI
Gerd Hoffmann4e307fc2009-12-08 13:11:37 +01003420@item -monitor @var{dev}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003421@findex -monitor
blueswir15824d652009-03-28 06:44:27 +00003422Redirect the monitor to host device @var{dev} (same devices as the
3423serial port).
3424The default device is @code{vc} in graphical mode and @code{stdio} in
3425non graphical mode.
Luiz Capitulino70e098a2013-05-16 12:02:55 -04003426Use @code{-monitor none} to disable the default monitor.
blueswir15824d652009-03-28 06:44:27 +00003427ETEXI
Gerd Hoffmann6ca55822009-12-08 13:11:52 +01003428DEF("qmp", HAS_ARG, QEMU_OPTION_qmp, \
Blue Swirlad960902010-03-29 19:23:52 +00003429 "-qmp dev like -monitor but opens in 'control' mode\n",
3430 QEMU_ARCH_ALL)
Stefan Weil95d5f082010-01-20 22:25:27 +01003431STEXI
3432@item -qmp @var{dev}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003433@findex -qmp
Stefan Weil95d5f082010-01-20 22:25:27 +01003434Like -monitor but opens in 'control' mode.
3435ETEXI
Max Reitz4821cd42014-11-17 13:31:04 +01003436DEF("qmp-pretty", HAS_ARG, QEMU_OPTION_qmp_pretty, \
3437 "-qmp-pretty dev like -qmp but uses pretty JSON formatting\n",
3438 QEMU_ARCH_ALL)
3439STEXI
3440@item -qmp-pretty @var{dev}
3441@findex -qmp-pretty
3442Like -qmp but uses pretty JSON formatting.
3443ETEXI
blueswir15824d652009-03-28 06:44:27 +00003444
Gerd Hoffmann22a0e042009-12-08 13:11:51 +01003445DEF("mon", HAS_ARG, QEMU_OPTION_mon, \
Vicente Jimenez Aguilaref670722017-11-14 09:11:27 +01003446 "-mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]\n", QEMU_ARCH_ALL)
Gerd Hoffmann22a0e042009-12-08 13:11:51 +01003447STEXI
Vicente Jimenez Aguilaref670722017-11-14 09:11:27 +01003448@item -mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]
Stefan Weil6616b2a2010-02-05 23:52:05 +01003449@findex -mon
Vicente Jimenez Aguilaref670722017-11-14 09:11:27 +01003450Setup monitor on chardev @var{name}. @code{pretty} turns on JSON pretty printing
3451easing human reading and debugging.
Gerd Hoffmann22a0e042009-12-08 13:11:51 +01003452ETEXI
3453
H. Peter Anvinc9f398e2009-12-29 13:51:36 -08003454DEF("debugcon", HAS_ARG, QEMU_OPTION_debugcon, \
Blue Swirlad960902010-03-29 19:23:52 +00003455 "-debugcon dev redirect the debug console to char device 'dev'\n",
3456 QEMU_ARCH_ALL)
H. Peter Anvinc9f398e2009-12-29 13:51:36 -08003457STEXI
3458@item -debugcon @var{dev}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003459@findex -debugcon
H. Peter Anvinc9f398e2009-12-29 13:51:36 -08003460Redirect the debug console to host device @var{dev} (same devices as the
3461serial port). The debug console is an I/O port which is typically port
34620xe9; writing to that I/O port sends output to this device.
3463The default device is @code{vc} in graphical mode and @code{stdio} in
3464non graphical mode.
3465ETEXI
3466
blueswir15824d652009-03-28 06:44:27 +00003467DEF("pidfile", HAS_ARG, QEMU_OPTION_pidfile, \
Blue Swirlad960902010-03-29 19:23:52 +00003468 "-pidfile file write PID to 'file'\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003469STEXI
3470@item -pidfile @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003471@findex -pidfile
blueswir15824d652009-03-28 06:44:27 +00003472Store the QEMU process PID in @var{file}. It is useful if you launch QEMU
3473from a script.
3474ETEXI
3475
aurel321b530a62009-04-05 20:08:59 +00003476DEF("singlestep", 0, QEMU_OPTION_singlestep, \
Blue Swirlad960902010-03-29 19:23:52 +00003477 "-singlestep always run in singlestep mode\n", QEMU_ARCH_ALL)
aurel321b530a62009-04-05 20:08:59 +00003478STEXI
3479@item -singlestep
Stefan Weil6616b2a2010-02-05 23:52:05 +01003480@findex -singlestep
aurel321b530a62009-04-05 20:08:59 +00003481Run the emulation in single step mode.
3482ETEXI
3483
Igor Mammedov047f7032018-05-11 19:24:43 +02003484DEF("preconfig", 0, QEMU_OPTION_preconfig, \
Markus Armbruster361ac942018-07-05 11:14:02 +02003485 "--preconfig pause QEMU before machine is initialized (experimental)\n",
Igor Mammedov047f7032018-05-11 19:24:43 +02003486 QEMU_ARCH_ALL)
3487STEXI
3488@item --preconfig
3489@findex --preconfig
3490Pause QEMU for interactive configuration before the machine is created,
3491which allows querying and configuring properties that will affect
Markus Armbruster361ac942018-07-05 11:14:02 +02003492machine initialization. Use QMP command 'x-exit-preconfig' to exit
3493the preconfig state and move to the next state (i.e. run guest if -S
3494isn't used or pause the second time if -S is used). This option is
3495experimental.
Igor Mammedov047f7032018-05-11 19:24:43 +02003496ETEXI
3497
blueswir15824d652009-03-28 06:44:27 +00003498DEF("S", 0, QEMU_OPTION_S, \
Blue Swirlad960902010-03-29 19:23:52 +00003499 "-S freeze CPU at startup (use 'c' to start execution)\n",
3500 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003501STEXI
3502@item -S
Stefan Weil6616b2a2010-02-05 23:52:05 +01003503@findex -S
blueswir15824d652009-03-28 06:44:27 +00003504Do not start CPU at startup (you must type 'c' in the monitor).
3505ETEXI
3506
Satoru Moriya888a6bc2013-04-19 16:42:06 +02003507DEF("realtime", HAS_ARG, QEMU_OPTION_realtime,
3508 "-realtime [mlock=on|off]\n"
3509 " run qemu with realtime features\n"
3510 " mlock=on|off controls mlock support (default: on)\n",
3511 QEMU_ARCH_ALL)
3512STEXI
3513@item -realtime mlock=on|off
3514@findex -realtime
3515Run qemu with realtime features.
3516mlocking qemu and guest memory can be enabled via @option{mlock=on}
3517(enabled by default).
3518ETEXI
3519
Michael S. Tsirkin6f131f12018-06-22 22:22:05 +03003520DEF("overcommit", HAS_ARG, QEMU_OPTION_overcommit,
BALATON Zoltandfaa7d52018-07-16 21:12:08 +02003521 "-overcommit [mem-lock=on|off][cpu-pm=on|off]\n"
Michael S. Tsirkin6f131f12018-06-22 22:22:05 +03003522 " run qemu with overcommit hints\n"
3523 " mem-lock=on|off controls memory lock support (default: off)\n"
3524 " cpu-pm=on|off controls cpu power management (default: off)\n",
3525 QEMU_ARCH_ALL)
3526STEXI
3527@item -overcommit mem-lock=on|off
3528@item -overcommit cpu-pm=on|off
3529@findex -overcommit
3530Run qemu with hints about host resource overcommit. The default is
3531to assume that host overcommits all resources.
3532
3533Locking qemu and guest memory can be enabled via @option{mem-lock=on} (disabled
3534by default). This works when host memory is not overcommitted and reduces the
3535worst-case latency for guest. This is equivalent to @option{realtime}.
3536
3537Guest ability to manage power state of host cpus (increasing latency for other
3538processes on the same host cpu, but decreasing latency for guest) can be
3539enabled via @option{cpu-pm=on} (disabled by default). This works best when
3540host CPU is not overcommitted. When used, host estimates of CPU cycle and power
3541utilization will be incorrect, not taking into account guest idle time.
3542ETEXI
3543
aliguori59030a82009-04-05 18:43:41 +00003544DEF("gdb", HAS_ARG, QEMU_OPTION_gdb, \
Blue Swirlad960902010-03-29 19:23:52 +00003545 "-gdb dev wait for gdb connection on 'dev'\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003546STEXI
aliguori59030a82009-04-05 18:43:41 +00003547@item -gdb @var{dev}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003548@findex -gdb
aliguori59030a82009-04-05 18:43:41 +00003549Wait for gdb connection on device @var{dev} (@pxref{gdb_usage}). Typical
3550connections will likely be TCP-based, but also UDP, pseudo TTY, or even
Stefan Weilb65ee4f2012-05-11 22:25:50 +02003551stdio are reasonable use case. The latter is allowing to start QEMU from
aliguori59030a82009-04-05 18:43:41 +00003552within gdb and establish the connection via a pipe:
3553@example
Stefan Weil3804da92012-05-11 22:21:50 +02003554(gdb) target remote | exec qemu-system-i386 -gdb stdio ...
aliguori59030a82009-04-05 18:43:41 +00003555@end example
blueswir15824d652009-03-28 06:44:27 +00003556ETEXI
3557
aliguori59030a82009-04-05 18:43:41 +00003558DEF("s", 0, QEMU_OPTION_s, \
Blue Swirlad960902010-03-29 19:23:52 +00003559 "-s shorthand for -gdb tcp::" DEFAULT_GDBSTUB_PORT "\n",
3560 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003561STEXI
aliguori59030a82009-04-05 18:43:41 +00003562@item -s
Stefan Weil6616b2a2010-02-05 23:52:05 +01003563@findex -s
aliguori59030a82009-04-05 18:43:41 +00003564Shorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234
3565(@pxref{gdb_usage}).
blueswir15824d652009-03-28 06:44:27 +00003566ETEXI
3567
3568DEF("d", HAS_ARG, QEMU_OPTION_d, \
Peter Maydell989b6972013-02-26 17:52:40 +00003569 "-d item1,... enable logging of specified items (use '-d help' for a list of log items)\n",
Blue Swirlad960902010-03-29 19:23:52 +00003570 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003571STEXI
Peter Maydell989b6972013-02-26 17:52:40 +00003572@item -d @var{item1}[,...]
Stefan Weil6616b2a2010-02-05 23:52:05 +01003573@findex -d
Peter Maydell989b6972013-02-26 17:52:40 +00003574Enable logging of specified items. Use '-d help' for a list of log items.
blueswir15824d652009-03-28 06:44:27 +00003575ETEXI
3576
Matthew Fernandezc235d732011-06-07 16:32:40 +00003577DEF("D", HAS_ARG, QEMU_OPTION_D, \
Peter Maydell989b6972013-02-26 17:52:40 +00003578 "-D logfile output log to logfile (default stderr)\n",
Matthew Fernandezc235d732011-06-07 16:32:40 +00003579 QEMU_ARCH_ALL)
3580STEXI
Stefan Weil8bd383b2012-05-11 22:40:50 +02003581@item -D @var{logfile}
Matthew Fernandezc235d732011-06-07 16:32:40 +00003582@findex -D
Peter Maydell989b6972013-02-26 17:52:40 +00003583Output log in @var{logfile} instead of to stderr
Matthew Fernandezc235d732011-06-07 16:32:40 +00003584ETEXI
3585
Alex Bennée35145522016-03-15 14:30:20 +00003586DEF("dfilter", HAS_ARG, QEMU_OPTION_DFILTER, \
3587 "-dfilter range,.. filter debug output to range of addresses (useful for -d cpu,exec,etc..)\n",
3588 QEMU_ARCH_ALL)
3589STEXI
3590@item -dfilter @var{range1}[,...]
3591@findex -dfilter
3592Filter debug output to that relevant to a range of target addresses. The filter
3593spec can be either @var{start}+@var{size}, @var{start}-@var{size} or
3594@var{start}..@var{end} where @var{start} @var{end} and @var{size} are the
3595addresses and sizes required. For example:
3596@example
3597 -dfilter 0x8000..0x8fff,0xffffffc000080000+0x200,0xffffffc000060000-0x1000
3598@end example
3599Will dump output for any code in the 0x1000 sized block starting at 0x8000 and
3600the 0x200 sized block starting at 0xffffffc000080000 and another 0x1000 sized
3601block starting at 0xffffffc00005f000.
3602ETEXI
3603
blueswir15824d652009-03-28 06:44:27 +00003604DEF("L", HAS_ARG, QEMU_OPTION_L, \
Blue Swirlad960902010-03-29 19:23:52 +00003605 "-L path set the directory for the BIOS, VGA BIOS and keymaps\n",
3606 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003607STEXI
3608@item -L @var{path}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003609@findex -L
blueswir15824d652009-03-28 06:44:27 +00003610Set the directory for the BIOS, VGA BIOS and keymaps.
Richard W.M. Jones37146e72016-05-16 17:34:35 +01003611
3612To list all the data directories, use @code{-L help}.
blueswir15824d652009-03-28 06:44:27 +00003613ETEXI
3614
3615DEF("bios", HAS_ARG, QEMU_OPTION_bios, \
Blue Swirlad960902010-03-29 19:23:52 +00003616 "-bios file set the filename for the BIOS\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003617STEXI
3618@item -bios @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003619@findex -bios
blueswir15824d652009-03-28 06:44:27 +00003620Set the filename for the BIOS.
3621ETEXI
3622
blueswir15824d652009-03-28 06:44:27 +00003623DEF("enable-kvm", 0, QEMU_OPTION_enable_kvm, \
Blue Swirlad960902010-03-29 19:23:52 +00003624 "-enable-kvm enable KVM full virtualization support\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003625STEXI
3626@item -enable-kvm
Stefan Weil6616b2a2010-02-05 23:52:05 +01003627@findex -enable-kvm
blueswir15824d652009-03-28 06:44:27 +00003628Enable KVM full virtualization support. This option is only available
3629if KVM support is enabled when compiling.
3630ETEXI
3631
aliguorie37630c2009-04-22 15:19:10 +00003632DEF("xen-domid", HAS_ARG, QEMU_OPTION_xen_domid,
Blue Swirlad960902010-03-29 19:23:52 +00003633 "-xen-domid id specify xen guest domain id\n", QEMU_ARCH_ALL)
aliguorie37630c2009-04-22 15:19:10 +00003634DEF("xen-attach", 0, QEMU_OPTION_xen_attach,
3635 "-xen-attach attach to existing xen domain\n"
Anthony PERARD1077bca2018-09-14 12:18:30 +01003636 " libxl will use this when starting QEMU\n",
Blue Swirlad960902010-03-29 19:23:52 +00003637 QEMU_ARCH_ALL)
Paul Durrant1c599472017-03-22 09:39:15 +00003638DEF("xen-domid-restrict", 0, QEMU_OPTION_xen_domid_restrict,
3639 "-xen-domid-restrict restrict set of available xen operations\n"
3640 " to specified domain id. (Does not affect\n"
3641 " xenpv machine type).\n",
3642 QEMU_ARCH_ALL)
Stefan Weil95d5f082010-01-20 22:25:27 +01003643STEXI
3644@item -xen-domid @var{id}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003645@findex -xen-domid
Stefan Weil95d5f082010-01-20 22:25:27 +01003646Specify xen guest domain @var{id} (XEN only).
Stefan Weil95d5f082010-01-20 22:25:27 +01003647@item -xen-attach
Stefan Weil6616b2a2010-02-05 23:52:05 +01003648@findex -xen-attach
Stefan Weil95d5f082010-01-20 22:25:27 +01003649Attach to existing xen domain.
Anthony PERARD1077bca2018-09-14 12:18:30 +01003650libxl will use this when starting QEMU (XEN only).
Paul Durrant1c599472017-03-22 09:39:15 +00003651@findex -xen-domid-restrict
3652Restrict set of available xen operations to specified domain id (XEN only).
Stefan Weil95d5f082010-01-20 22:25:27 +01003653ETEXI
aliguorie37630c2009-04-22 15:19:10 +00003654
blueswir15824d652009-03-28 06:44:27 +00003655DEF("no-reboot", 0, QEMU_OPTION_no_reboot, \
Blue Swirlad960902010-03-29 19:23:52 +00003656 "-no-reboot exit instead of rebooting\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003657STEXI
3658@item -no-reboot
Stefan Weil6616b2a2010-02-05 23:52:05 +01003659@findex -no-reboot
blueswir15824d652009-03-28 06:44:27 +00003660Exit instead of rebooting.
3661ETEXI
3662
3663DEF("no-shutdown", 0, QEMU_OPTION_no_shutdown, \
Blue Swirlad960902010-03-29 19:23:52 +00003664 "-no-shutdown stop before shutdown\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003665STEXI
3666@item -no-shutdown
Stefan Weil6616b2a2010-02-05 23:52:05 +01003667@findex -no-shutdown
blueswir15824d652009-03-28 06:44:27 +00003668Don't exit QEMU on guest shutdown, but instead only stop the emulation.
3669This allows for instance switching to monitor to commit changes to the
3670disk image.
3671ETEXI
3672
3673DEF("loadvm", HAS_ARG, QEMU_OPTION_loadvm, \
3674 "-loadvm [tag|id]\n" \
Blue Swirlad960902010-03-29 19:23:52 +00003675 " start right away with a saved state (loadvm in monitor)\n",
3676 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003677STEXI
3678@item -loadvm @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003679@findex -loadvm
blueswir15824d652009-03-28 06:44:27 +00003680Start right away with a saved state (@code{loadvm} in monitor)
3681ETEXI
3682
3683#ifndef _WIN32
3684DEF("daemonize", 0, QEMU_OPTION_daemonize, \
Blue Swirlad960902010-03-29 19:23:52 +00003685 "-daemonize daemonize QEMU after initializing\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003686#endif
3687STEXI
3688@item -daemonize
Stefan Weil6616b2a2010-02-05 23:52:05 +01003689@findex -daemonize
blueswir15824d652009-03-28 06:44:27 +00003690Daemonize the QEMU process after initialization. QEMU will not detach from
3691standard IO until it is ready to receive connections on any of its devices.
3692This option is a useful way for external programs to launch QEMU without having
3693to cope with initialization race conditions.
3694ETEXI
3695
3696DEF("option-rom", HAS_ARG, QEMU_OPTION_option_rom, \
Blue Swirlad960902010-03-29 19:23:52 +00003697 "-option-rom rom load a file, rom, into the option ROM space\n",
3698 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003699STEXI
3700@item -option-rom @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003701@findex -option-rom
blueswir15824d652009-03-28 06:44:27 +00003702Load the contents of @var{file} as an option ROM.
3703This option is useful to load things like EtherBoot.
3704ETEXI
3705
Jan Kiszka1ed2fc12009-09-15 13:36:04 +02003706DEF("rtc", HAS_ARG, QEMU_OPTION_rtc, \
Artem Pisarenko238d1242018-10-18 13:12:52 +06003707 "-rtc [base=utc|localtime|<datetime>][,clock=host|rt|vm][,driftfix=none|slew]\n" \
Blue Swirlad960902010-03-29 19:23:52 +00003708 " set the RTC base and clock, enable drift fix for clock ticks (x86 only)\n",
3709 QEMU_ARCH_ALL)
Jan Kiszka1ed2fc12009-09-15 13:36:04 +02003710
blueswir15824d652009-03-28 06:44:27 +00003711STEXI
3712
Artem Pisarenko238d1242018-10-18 13:12:52 +06003713@item -rtc [base=utc|localtime|@var{datetime}][,clock=host|rt|vm][,driftfix=none|slew]
Stefan Weil6616b2a2010-02-05 23:52:05 +01003714@findex -rtc
Jan Kiszka1ed2fc12009-09-15 13:36:04 +02003715Specify @option{base} as @code{utc} or @code{localtime} to let the RTC start at the current
3716UTC or local time, respectively. @code{localtime} is required for correct date in
Artem Pisarenko238d1242018-10-18 13:12:52 +06003717MS-DOS or Windows. To start at a specific point in time, provide @var{datetime} in the
Jan Kiszka1ed2fc12009-09-15 13:36:04 +02003718format @code{2006-06-17T16:01:21} or @code{2006-06-17}. The default base is UTC.
3719
Michael Tokarev9d85d552014-04-07 13:34:58 +04003720By default the RTC is driven by the host system time. This allows using of the
Jan Kiszka68752042009-09-15 13:36:04 +02003721RTC as accurate reference clock inside the guest, specifically if the host
3722time is smoothly following an accurate external reference clock, e.g. via NTP.
Paolo Bonzini78808142012-03-30 10:31:21 +00003723If you want to isolate the guest time from the host, you can set @option{clock}
Artem Pisarenko238d1242018-10-18 13:12:52 +06003724to @code{rt} instead, which provides a host monotonic clock if host support it.
3725To even prevent the RTC from progressing during suspension, you can set @option{clock}
3726to @code{vm} (virtual clock). @samp{clock=vm} is recommended especially in
3727icount mode in order to preserve determinism; however, note that in icount mode
3728the speed of the virtual clock is variable and can in general differ from the
3729host clock.
Jan Kiszka68752042009-09-15 13:36:04 +02003730
Jan Kiszka1ed2fc12009-09-15 13:36:04 +02003731Enable @option{driftfix} (i386 targets only) if you experience time drift problems,
3732specifically with Windows' ACPI HAL. This option will try to figure out how
3733many timer interrupts were not processed by the Windows guest and will
3734re-inject them.
blueswir15824d652009-03-28 06:44:27 +00003735ETEXI
3736
3737DEF("icount", HAS_ARG, QEMU_OPTION_icount, \
Pavel Dovgalyuk9c2037d2017-01-24 10:17:47 +03003738 "-icount [shift=N|auto][,align=on|off][,sleep=on|off,rr=record|replay,rrfile=<filename>,rrsnapshot=<snapshot>]\n" \
aliguoribc14ca22009-04-05 18:43:37 +00003739 " enable virtual instruction counter with 2^N clock ticks per\n" \
Victor CLEMENTf1f4b572015-05-29 17:14:05 +02003740 " instruction, enable aligning the host and virtual clocks\n" \
3741 " or disable real time cpu sleeping\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003742STEXI
Pavel Dovgalyuk9c2037d2017-01-24 10:17:47 +03003743@item -icount [shift=@var{N}|auto][,rr=record|replay,rrfile=@var{filename},rrsnapshot=@var{snapshot}]
Stefan Weil6616b2a2010-02-05 23:52:05 +01003744@findex -icount
blueswir15824d652009-03-28 06:44:27 +00003745Enable virtual instruction counter. The virtual cpu will execute one
Kevin Wolf4e257e52009-10-09 10:58:36 +02003746instruction every 2^@var{N} ns of virtual time. If @code{auto} is specified
blueswir15824d652009-03-28 06:44:27 +00003747then the virtual cpu speed will be automatically adjusted to keep virtual
3748time within a few seconds of real time.
3749
Victor CLEMENTf1f4b572015-05-29 17:14:05 +02003750When the virtual cpu is sleeping, the virtual time will advance at default
Pranith Kumar778d9f92016-02-26 10:16:51 -05003751speed unless @option{sleep=on|off} is specified.
3752With @option{sleep=on|off}, the virtual time will jump to the next timer deadline
Victor CLEMENTf1f4b572015-05-29 17:14:05 +02003753instantly whenever the virtual cpu goes to sleep mode and will not advance
3754if no timer is enabled. This behavior give deterministic execution times from
3755the guest point of view.
3756
blueswir15824d652009-03-28 06:44:27 +00003757Note that while this option can give deterministic behavior, it does not
3758provide cycle accurate emulation. Modern CPUs contain superscalar out of
3759order cores with complex cache hierarchies. The number of instructions
3760executed often has little or no correlation with actual performance.
Sebastian Tanasea8bfac32014-07-25 11:56:29 +02003761
Daniel P. Berrangeb6af0972015-08-26 12:17:13 +01003762@option{align=on} will activate the delay algorithm which will try
Sebastian Tanasea8bfac32014-07-25 11:56:29 +02003763to synchronise the host clock and the virtual clock. The goal is to
3764have a guest running at the real frequency imposed by the shift option.
3765Whenever the guest clock is behind the host clock and if
Michael Tokarev82597612015-04-27 11:12:49 +03003766@option{align=on} is specified then we print a message to the user
Sebastian Tanasea8bfac32014-07-25 11:56:29 +02003767to inform about the delay.
3768Currently this option does not work when @option{shift} is @code{auto}.
3769Note: The sync algorithm will work for those shift values for which
3770the guest clock runs ahead of the host clock. Typically this happens
3771when the shift value is high (how high depends on the host machine).
Pavel Dovgalyuk4c27b852015-09-17 19:25:18 +03003772
3773When @option{rr} option is specified deterministic record/replay is enabled.
3774Replay log is written into @var{filename} file in record mode and
3775read from this file in replay mode.
Pavel Dovgalyuk9c2037d2017-01-24 10:17:47 +03003776
3777Option rrsnapshot is used to create new vm snapshot named @var{snapshot}
3778at the start of execution recording. In replay mode this option is used
3779to load the initial VM state.
blueswir15824d652009-03-28 06:44:27 +00003780ETEXI
3781
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003782DEF("watchdog", HAS_ARG, QEMU_OPTION_watchdog, \
Xu Wangd7933ef2015-06-11 17:32:05 +02003783 "-watchdog model\n" \
Blue Swirlad960902010-03-29 19:23:52 +00003784 " enable virtual hardware watchdog [default=none]\n",
3785 QEMU_ARCH_ALL)
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003786STEXI
3787@item -watchdog @var{model}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003788@findex -watchdog
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003789Create a virtual hardware watchdog device. Once enabled (by a guest
3790action), the watchdog must be periodically polled by an agent inside
Xu Wangd7933ef2015-06-11 17:32:05 +02003791the guest or else the guest will be restarted. Choose a model for
3792which your guest has drivers.
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003793
Xu Wangd7933ef2015-06-11 17:32:05 +02003794The @var{model} is the model of hardware watchdog to emulate. Use
3795@code{-watchdog help} to list available hardware models. Only one
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003796watchdog can be enabled for a guest.
Xu Wangd7933ef2015-06-11 17:32:05 +02003797
3798The following models may be available:
3799@table @option
3800@item ib700
3801iBASE 700 is a very simple ISA watchdog with a single timer.
3802@item i6300esb
3803Intel 6300ESB I/O controller hub is a much more featureful PCI-based
3804dual-timer watchdog.
Xu Wang188f24c2015-02-05 18:28:32 +08003805@item diag288
3806A virtual watchdog for s390x backed by the diagnose 288 hypercall
3807(currently KVM only).
Xu Wangd7933ef2015-06-11 17:32:05 +02003808@end table
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003809ETEXI
3810
3811DEF("watchdog-action", HAS_ARG, QEMU_OPTION_watchdog_action, \
Markus Armbruster7ad92702017-10-02 16:03:07 +02003812 "-watchdog-action reset|shutdown|poweroff|inject-nmi|pause|debug|none\n" \
Blue Swirlad960902010-03-29 19:23:52 +00003813 " action when watchdog fires [default=reset]\n",
3814 QEMU_ARCH_ALL)
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003815STEXI
3816@item -watchdog-action @var{action}
Markus Armbrusterb8f490e2013-02-13 19:49:38 +01003817@findex -watchdog-action
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003818
3819The @var{action} controls what QEMU will do when the watchdog timer
3820expires.
3821The default is
3822@code{reset} (forcefully reset the guest).
3823Other possible actions are:
3824@code{shutdown} (attempt to gracefully shutdown the guest),
3825@code{poweroff} (forcefully poweroff the guest),
Markus Armbruster7ad92702017-10-02 16:03:07 +02003826@code{inject-nmi} (inject a NMI into the guest),
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003827@code{pause} (pause the guest),
3828@code{debug} (print a debug message and continue), or
3829@code{none} (do nothing).
3830
3831Note that the @code{shutdown} action requires that the guest responds
3832to ACPI signals, which it may not be able to do in the sort of
3833situations where the watchdog would have expired, and thus
3834@code{-watchdog-action shutdown} is not recommended for production use.
3835
3836Examples:
3837
3838@table @code
3839@item -watchdog i6300esb -watchdog-action pause
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02003840@itemx -watchdog ib700
Richard W.M. Jones9dd986c2009-04-25 13:56:19 +01003841@end table
3842ETEXI
3843
blueswir15824d652009-03-28 06:44:27 +00003844DEF("echr", HAS_ARG, QEMU_OPTION_echr, \
Blue Swirlad960902010-03-29 19:23:52 +00003845 "-echr chr set terminal escape character instead of ctrl-a\n",
3846 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003847STEXI
3848
Kevin Wolf4e257e52009-10-09 10:58:36 +02003849@item -echr @var{numeric_ascii_value}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003850@findex -echr
blueswir15824d652009-03-28 06:44:27 +00003851Change the escape character used for switching to the monitor when using
3852monitor and serial sharing. The default is @code{0x01} when using the
3853@code{-nographic} option. @code{0x01} is equal to pressing
3854@code{Control-a}. You can select a different character from the ascii
3855control keys where 1 through 26 map to Control-a through Control-z. For
3856instance you could use the either of the following to change the escape
3857character to Control-t.
3858@table @code
3859@item -echr 0x14
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02003860@itemx -echr 20
blueswir15824d652009-03-28 06:44:27 +00003861@end table
3862ETEXI
3863
blueswir15824d652009-03-28 06:44:27 +00003864DEF("show-cursor", 0, QEMU_OPTION_show_cursor, \
Blue Swirlad960902010-03-29 19:23:52 +00003865 "-show-cursor show cursor\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003866STEXI
Stefan Weil95d5f082010-01-20 22:25:27 +01003867@item -show-cursor
Stefan Weil6616b2a2010-02-05 23:52:05 +01003868@findex -show-cursor
Stefan Weil95d5f082010-01-20 22:25:27 +01003869Show cursor.
blueswir15824d652009-03-28 06:44:27 +00003870ETEXI
3871
3872DEF("tb-size", HAS_ARG, QEMU_OPTION_tb_size, \
Blue Swirlad960902010-03-29 19:23:52 +00003873 "-tb-size n set TB size\n", QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003874STEXI
Stefan Weil95d5f082010-01-20 22:25:27 +01003875@item -tb-size @var{n}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003876@findex -tb-size
Stefan Weil95d5f082010-01-20 22:25:27 +01003877Set TB size.
blueswir15824d652009-03-28 06:44:27 +00003878ETEXI
3879
3880DEF("incoming", HAS_ARG, QEMU_OPTION_incoming, \
Michael Tokarev7c601802015-02-10 22:40:47 +03003881 "-incoming tcp:[host]:port[,to=maxport][,ipv4][,ipv6]\n" \
3882 "-incoming rdma:host:port[,ipv4][,ipv6]\n" \
3883 "-incoming unix:socketpath\n" \
3884 " prepare for incoming migration, listen on\n" \
3885 " specified protocol and socket address\n" \
3886 "-incoming fd:fd\n" \
3887 "-incoming exec:cmdline\n" \
3888 " accept incoming migration on given file descriptor\n" \
Dr. David Alan Gilbert15970512015-05-29 19:52:52 +01003889 " or from given external command\n" \
3890 "-incoming defer\n" \
3891 " wait for the URI to be specified via migrate_incoming\n",
Blue Swirlad960902010-03-29 19:23:52 +00003892 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003893STEXI
Michael Tokarev7c601802015-02-10 22:40:47 +03003894@item -incoming tcp:[@var{host}]:@var{port}[,to=@var{maxport}][,ipv4][,ipv6]
Markus Armbrusterf9cfd652015-06-15 14:35:59 +02003895@itemx -incoming rdma:@var{host}:@var{port}[,ipv4][,ipv6]
Stefan Weil6616b2a2010-02-05 23:52:05 +01003896@findex -incoming
Michael Tokarev7c601802015-02-10 22:40:47 +03003897Prepare for incoming migration, listen on a given tcp port.
3898
3899@item -incoming unix:@var{socketpath}
3900Prepare for incoming migration, listen on a given unix socket.
3901
3902@item -incoming fd:@var{fd}
3903Accept incoming migration from a given filedescriptor.
3904
3905@item -incoming exec:@var{cmdline}
3906Accept incoming migration as an output from specified external command.
Dr. David Alan Gilbert15970512015-05-29 19:52:52 +01003907
3908@item -incoming defer
3909Wait for the URI to be specified via migrate_incoming. The monitor can
3910be used to change settings (such as migration parameters) prior to issuing
3911the migrate_incoming to allow the migration to begin.
blueswir15824d652009-03-28 06:44:27 +00003912ETEXI
3913
Ashijeet Acharyad15c05f2017-01-16 17:01:51 +05303914DEF("only-migratable", 0, QEMU_OPTION_only_migratable, \
3915 "-only-migratable allow only migratable devices\n", QEMU_ARCH_ALL)
3916STEXI
3917@item -only-migratable
3918@findex -only-migratable
3919Only allow migratable devices. Devices will not be allowed to enter an
3920unmigratable state.
3921ETEXI
3922
Gerd Hoffmannd8c208d2009-12-08 13:11:46 +01003923DEF("nodefaults", 0, QEMU_OPTION_nodefaults, \
Blue Swirlad960902010-03-29 19:23:52 +00003924 "-nodefaults don't create default devices\n", QEMU_ARCH_ALL)
Gerd Hoffmannd8c208d2009-12-08 13:11:46 +01003925STEXI
Stefan Weil3dbf2c72010-01-16 18:19:44 +01003926@item -nodefaults
Stefan Weil6616b2a2010-02-05 23:52:05 +01003927@findex -nodefaults
Michal Novotny66c19bf2012-07-16 14:35:10 +02003928Don't create default devices. Normally, QEMU sets the default devices like serial
3929port, parallel port, virtual console, monitor device, VGA adapter, floppy and
3930CD-ROM drive and others. The @code{-nodefaults} option will disable all those
3931default devices.
Gerd Hoffmannd8c208d2009-12-08 13:11:46 +01003932ETEXI
3933
blueswir15824d652009-03-28 06:44:27 +00003934#ifndef _WIN32
3935DEF("chroot", HAS_ARG, QEMU_OPTION_chroot, \
Blue Swirlad960902010-03-29 19:23:52 +00003936 "-chroot dir chroot to dir just before starting the VM\n",
3937 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003938#endif
3939STEXI
Kevin Wolf4e257e52009-10-09 10:58:36 +02003940@item -chroot @var{dir}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003941@findex -chroot
blueswir15824d652009-03-28 06:44:27 +00003942Immediately before starting guest execution, chroot to the specified
3943directory. Especially useful in combination with -runas.
3944ETEXI
3945
3946#ifndef _WIN32
3947DEF("runas", HAS_ARG, QEMU_OPTION_runas, \
Ian Jackson2c42f1e2017-09-15 18:10:44 +01003948 "-runas user change to user id user just before starting the VM\n" \
3949 " user can be numeric uid:gid instead\n",
Blue Swirlad960902010-03-29 19:23:52 +00003950 QEMU_ARCH_ALL)
blueswir15824d652009-03-28 06:44:27 +00003951#endif
3952STEXI
Kevin Wolf4e257e52009-10-09 10:58:36 +02003953@item -runas @var{user}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003954@findex -runas
blueswir15824d652009-03-28 06:44:27 +00003955Immediately before starting guest execution, drop root privileges, switching
3956to the specified user.
3957ETEXI
3958
blueswir15824d652009-03-28 06:44:27 +00003959DEF("prom-env", HAS_ARG, QEMU_OPTION_prom_env,
3960 "-prom-env variable=value\n"
Blue Swirlad960902010-03-29 19:23:52 +00003961 " set OpenBIOS nvram variables\n",
3962 QEMU_ARCH_PPC | QEMU_ARCH_SPARC)
Stefan Weil95d5f082010-01-20 22:25:27 +01003963STEXI
3964@item -prom-env @var{variable}=@var{value}
Stefan Weil6616b2a2010-02-05 23:52:05 +01003965@findex -prom-env
Stefan Weil95d5f082010-01-20 22:25:27 +01003966Set OpenBIOS nvram @var{variable} to given @var{value} (PPC, SPARC only).
3967ETEXI
blueswir15824d652009-03-28 06:44:27 +00003968DEF("semihosting", 0, QEMU_OPTION_semihosting,
Michael Wallef7bbcfb2014-04-22 20:18:42 +02003969 "-semihosting semihosting mode\n",
Leon Alrae3b3c1692015-06-19 11:08:43 +01003970 QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 |
Sandra Loosemore413a99a2019-04-03 13:53:05 -06003971 QEMU_ARCH_MIPS | QEMU_ARCH_NIOS2)
Stefan Weil95d5f082010-01-20 22:25:27 +01003972STEXI
3973@item -semihosting
Stefan Weil6616b2a2010-02-05 23:52:05 +01003974@findex -semihosting
Sandra Loosemore413a99a2019-04-03 13:53:05 -06003975Enable semihosting mode (ARM, M68K, Xtensa, MIPS, Nios II only).
Liviu Ionescua38bb072014-12-11 12:07:48 +00003976ETEXI
3977DEF("semihosting-config", HAS_ARG, QEMU_OPTION_semihosting_config,
Leon Alraea59d31a2015-06-19 14:17:45 +01003978 "-semihosting-config [enable=on|off][,target=native|gdb|auto][,arg=str[,...]]\n" \
3979 " semihosting configuration\n",
Leon Alrae3b3c1692015-06-19 11:08:43 +01003980QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 |
Sandra Loosemore413a99a2019-04-03 13:53:05 -06003981QEMU_ARCH_MIPS | QEMU_ARCH_NIOS2)
Liviu Ionescua38bb072014-12-11 12:07:48 +00003982STEXI
Leon Alraea59d31a2015-06-19 14:17:45 +01003983@item -semihosting-config [enable=on|off][,target=native|gdb|auto][,arg=str[,...]]
Liviu Ionescua38bb072014-12-11 12:07:48 +00003984@findex -semihosting-config
Sandra Loosemore413a99a2019-04-03 13:53:05 -06003985Enable and configure semihosting (ARM, M68K, Xtensa, MIPS, Nios II only).
Leon Alraea59d31a2015-06-19 14:17:45 +01003986@table @option
3987@item target=@code{native|gdb|auto}
3988Defines where the semihosting calls will be addressed, to QEMU (@code{native})
3989or to GDB (@code{gdb}). The default is @code{auto}, which means @code{gdb}
3990during debug sessions and @code{native} otherwise.
3991@item arg=@var{str1},arg=@var{str2},...
3992Allows the user to pass input arguments, and can be used multiple times to build
3993up a list. The old-style @code{-kernel}/@code{-append} method of passing a
3994command line is still supported for backward compatibility. If both the
3995@code{--semihosting-config arg} and the @code{-kernel}/@code{-append} are
3996specified, the former is passed to semihosting as it always takes precedence.
3997@end table
Stefan Weil95d5f082010-01-20 22:25:27 +01003998ETEXI
blueswir15824d652009-03-28 06:44:27 +00003999DEF("old-param", 0, QEMU_OPTION_old_param,
Blue Swirlad960902010-03-29 19:23:52 +00004000 "-old-param old param mode\n", QEMU_ARCH_ARM)
Stefan Weil95d5f082010-01-20 22:25:27 +01004001STEXI
4002@item -old-param
Stefan Weil6616b2a2010-02-05 23:52:05 +01004003@findex -old-param (ARM)
Stefan Weil95d5f082010-01-20 22:25:27 +01004004Old param mode (ARM only).
4005ETEXI
4006
Eduardo Otubo7d76ad42012-08-14 18:44:08 -03004007DEF("sandbox", HAS_ARG, QEMU_OPTION_sandbox, \
Eduardo Otubo73a1e642017-03-13 22:13:27 +01004008 "-sandbox on[,obsolete=allow|deny][,elevateprivileges=allow|deny|children]\n" \
Eduardo Otubo24f8cdc2017-03-13 22:18:51 +01004009 " [,spawn=allow|deny][,resourcecontrol=allow|deny]\n" \
Eduardo Otubo2b716fa2017-03-01 23:17:29 +01004010 " Enable seccomp mode 2 system call filter (default 'off').\n" \
4011 " use 'obsolete' to allow obsolete system calls that are provided\n" \
4012 " by the kernel, but typically no longer used by modern\n" \
Eduardo Otubo73a1e642017-03-13 22:13:27 +01004013 " C library implementations.\n" \
4014 " use 'elevateprivileges' to allow or deny QEMU process to elevate\n" \
4015 " its privileges by blacklisting all set*uid|gid system calls.\n" \
4016 " The value 'children' will deny set*uid|gid system calls for\n" \
Eduardo Otubo995a2262017-03-13 22:16:01 +01004017 " main QEMU process but will allow forks and execves to run unprivileged\n" \
4018 " use 'spawn' to avoid QEMU to spawn new threads or processes by\n" \
Eduardo Otubo24f8cdc2017-03-13 22:18:51 +01004019 " blacklisting *fork and execve\n" \
4020 " use 'resourcecontrol' to disable process affinity and schedular priority\n",
Eduardo Otubo7d76ad42012-08-14 18:44:08 -03004021 QEMU_ARCH_ALL)
4022STEXI
Eduardo Otubo24f8cdc2017-03-13 22:18:51 +01004023@item -sandbox @var{arg}[,obsolete=@var{string}][,elevateprivileges=@var{string}][,spawn=@var{string}][,resourcecontrol=@var{string}]
Eduardo Otubo7d76ad42012-08-14 18:44:08 -03004024@findex -sandbox
4025Enable Seccomp mode 2 system call filter. 'on' will enable syscall filtering and 'off' will
4026disable it. The default is 'off'.
Eduardo Otubo2b716fa2017-03-01 23:17:29 +01004027@table @option
4028@item obsolete=@var{string}
4029Enable Obsolete system calls
Eduardo Otubo73a1e642017-03-13 22:13:27 +01004030@item elevateprivileges=@var{string}
4031Disable set*uid|gid system calls
Eduardo Otubo995a2262017-03-13 22:16:01 +01004032@item spawn=@var{string}
4033Disable *fork and execve
Eduardo Otubo24f8cdc2017-03-13 22:18:51 +01004034@item resourcecontrol=@var{string}
4035Disable process affinity and schedular priority
Eduardo Otubo2b716fa2017-03-01 23:17:29 +01004036@end table
Eduardo Otubo7d76ad42012-08-14 18:44:08 -03004037ETEXI
4038
Gerd Hoffmann715a6642009-10-14 10:39:28 +02004039DEF("readconfig", HAS_ARG, QEMU_OPTION_readconfig,
Blue Swirlad960902010-03-29 19:23:52 +00004040 "-readconfig <file>\n", QEMU_ARCH_ALL)
Stefan Weil3dbf2c72010-01-16 18:19:44 +01004041STEXI
4042@item -readconfig @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01004043@findex -readconfig
Michal Novotnyed24cfa2012-07-16 14:28:32 +02004044Read device configuration from @var{file}. This approach is useful when you want to spawn
4045QEMU process with many command line options but you don't want to exceed the command line
4046character limit.
Stefan Weil3dbf2c72010-01-16 18:19:44 +01004047ETEXI
Gerd Hoffmann715a6642009-10-14 10:39:28 +02004048DEF("writeconfig", HAS_ARG, QEMU_OPTION_writeconfig,
4049 "-writeconfig <file>\n"
Blue Swirlad960902010-03-29 19:23:52 +00004050 " read/write config file\n", QEMU_ARCH_ALL)
Stefan Weil3dbf2c72010-01-16 18:19:44 +01004051STEXI
4052@item -writeconfig @var{file}
Stefan Weil6616b2a2010-02-05 23:52:05 +01004053@findex -writeconfig
Michal Novotnyed24cfa2012-07-16 14:28:32 +02004054Write device configuration to @var{file}. The @var{file} can be either filename to save
4055command line and device configuration into file or dash @code{-}) character to print the
4056output to stdout. This can be later used as input file for @code{-readconfig} option.
Stefan Weil3dbf2c72010-01-16 18:19:44 +01004057ETEXI
Thomas Huth2feac452018-08-21 12:59:56 +02004058
Eduardo Habkostf29a5612012-05-02 13:07:29 -03004059DEF("no-user-config", 0, QEMU_OPTION_nouserconfig,
4060 "-no-user-config\n"
Eduardo Habkost3478eae2017-10-04 00:00:25 -03004061 " do not load default user-provided config files at startup\n",
Eduardo Habkostf29a5612012-05-02 13:07:29 -03004062 QEMU_ARCH_ALL)
4063STEXI
4064@item -no-user-config
4065@findex -no-user-config
4066The @code{-no-user-config} option makes QEMU not load any of the user-provided
Eduardo Habkost3478eae2017-10-04 00:00:25 -03004067config files on @var{sysconfdir}.
Anthony Liguori292444c2010-01-21 10:57:58 -06004068ETEXI
Thomas Huth2feac452018-08-21 12:59:56 +02004069
Prerna Saxenaab6540d2010-08-09 11:48:32 +01004070DEF("trace", HAS_ARG, QEMU_OPTION_trace,
Paolo Bonzini10578a22016-01-07 16:55:26 +03004071 "-trace [[enable=]<pattern>][,events=<file>][,file=<file>]\n"
LluĂ­s23d15e82011-08-31 20:31:31 +02004072 " specify tracing options\n",
Prerna Saxenaab6540d2010-08-09 11:48:32 +01004073 QEMU_ARCH_ALL)
4074STEXI
LluĂ­s23d15e82011-08-31 20:31:31 +02004075HXCOMM This line is not accurate, as some sub-options are backend-specific but
4076HXCOMM HX does not support conditional compilation of text.
Denis V. Luneve370ad92016-06-17 17:44:08 +03004077@item -trace [[enable=]@var{pattern}][,events=@var{file}][,file=@var{file}]
Prerna Saxenaab6540d2010-08-09 11:48:32 +01004078@findex -trace
Denis V. Luneveeb2b8f2016-06-17 17:44:09 +03004079@include qemu-option-trace.texi
Prerna Saxenaab6540d2010-08-09 11:48:32 +01004080ETEXI
Stefan Weil3dbf2c72010-01-16 18:19:44 +01004081
Markus Armbruster31e70d62013-02-13 19:49:37 +01004082HXCOMM Internal use
4083DEF("qtest", HAS_ARG, QEMU_OPTION_qtest, "", QEMU_ARCH_ALL)
4084DEF("qtest-log", HAS_ARG, QEMU_OPTION_qtest_log, "", QEMU_ARCH_ALL)
Anthony Liguoric7f0f3b2012-03-28 15:42:02 +02004085
Paul Moore0f669982012-08-03 14:39:21 -04004086#ifdef __linux__
4087DEF("enable-fips", 0, QEMU_OPTION_enablefips,
4088 "-enable-fips enable FIPS 140-2 compliance\n",
4089 QEMU_ARCH_ALL)
4090#endif
4091STEXI
4092@item -enable-fips
4093@findex -enable-fips
4094Enable FIPS 140-2 compliance mode.
4095ETEXI
4096
Jan Kiszkaa0dac022012-10-05 14:51:45 -03004097HXCOMM Deprecated by -machine accel=tcg property
Bruce Rogersc6e88b32012-11-20 07:11:21 -07004098DEF("no-kvm", 0, QEMU_OPTION_no_kvm, "", QEMU_ARCH_I386)
Jan Kiszkaa0dac022012-10-05 14:51:45 -03004099
Seiji Aguchi5e2ac512013-07-03 23:02:46 -04004100DEF("msg", HAS_ARG, QEMU_OPTION_msg,
4101 "-msg timestamp[=on|off]\n"
4102 " change the format of messages\n"
4103 " on|off controls leading timestamps (default:on)\n",
4104 QEMU_ARCH_ALL)
4105STEXI
4106@item -msg timestamp[=on|off]
4107@findex -msg
4108prepend a timestamp to each log message.(default:on)
4109ETEXI
4110
Amit Shahabfd9ce2014-06-20 18:56:08 +05304111DEF("dump-vmstate", HAS_ARG, QEMU_OPTION_dump_vmstate,
4112 "-dump-vmstate <file>\n"
4113 " Output vmstate information in JSON format to file.\n"
4114 " Use the scripts/vmstate-static-checker.py file to\n"
4115 " check for possible regressions in migration code\n"
Laurent Vivier23820532015-09-04 21:30:04 +02004116 " by comparing two such vmstate dumps.\n",
Amit Shahabfd9ce2014-06-20 18:56:08 +05304117 QEMU_ARCH_ALL)
4118STEXI
4119@item -dump-vmstate @var{file}
4120@findex -dump-vmstate
4121Dump json-encoded vmstate information for current machine type to file
4122in @var{file}
4123ETEXI
4124
Emilio G. Cota12df1892018-08-15 11:42:49 -04004125DEF("enable-sync-profile", 0, QEMU_OPTION_enable_sync_profile,
4126 "-enable-sync-profile\n"
4127 " enable synchronization profiling\n",
4128 QEMU_ARCH_ALL)
4129STEXI
4130@item -enable-sync-profile
4131@findex -enable-sync-profile
4132Enable synchronization profiling.
4133ETEXI
4134
Paolo Bonzini43f187a2017-01-04 13:50:37 +01004135STEXI
4136@end table
4137ETEXI
4138DEFHEADING()
Markus Armbrusterde6b4f92017-10-02 16:03:00 +02004139
4140DEFHEADING(Generic object creation:)
Paolo Bonzini43f187a2017-01-04 13:50:37 +01004141STEXI
4142@table @option
4143ETEXI
Daniel P. Berrangeb9174d42015-05-13 17:14:03 +01004144
4145DEF("object", HAS_ARG, QEMU_OPTION_object,
4146 "-object TYPENAME[,PROP1=VALUE1,...]\n"
4147 " create a new object of type TYPENAME setting properties\n"
4148 " in the order they are specified. Note that the 'id'\n"
4149 " property must be set. These objects are placed in the\n"
4150 " '/objects' path.\n",
4151 QEMU_ARCH_ALL)
4152STEXI
4153@item -object @var{typename}[,@var{prop1}=@var{value1},...]
4154@findex -object
4155Create a new object of type @var{typename} setting properties
4156in the order they are specified. Note that the 'id'
4157property must be set. These objects are placed in the
4158'/objects' path.
4159
4160@table @option
4161
Haozhong Zhang98376842017-12-11 15:28:04 +08004162@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 +01004163
4164Creates a memory file backend object, which can be used to back
Stefan Hajnoczic7cddce2017-11-28 16:15:28 +00004165the guest RAM with huge pages.
4166
4167The @option{id} parameter is a unique ID that will be used to reference this
4168memory region when configuring the @option{-numa} argument.
4169
4170The @option{size} option provides the size of the memory region, and accepts
4171common suffixes, eg @option{500M}.
4172
4173The @option{mem-path} provides the path to either a shared memory or huge page
4174filesystem mount.
4175
Daniel P. Berrangeb9174d42015-05-13 17:14:03 +01004176The @option{share} boolean option determines whether the memory
4177region is marked as private to QEMU, or shared. The latter allows
4178a co-operating external process to access the QEMU memory region.
Stefan Hajnoczic7cddce2017-11-28 16:15:28 +00004179
Marcel Apfelbaum06329cc2017-12-13 16:37:37 +02004180The @option{share} is also required for pvrdma devices due to
4181limitations in the RDMA API provided by Linux.
4182
4183Setting share=on might affect the ability to configure NUMA
4184bindings for the memory backend under some circumstances, see
4185Documentation/vm/numa_memory_policy.txt on the Linux kernel
4186source tree for additional details.
4187
Eduardo Habkost11ae6ed2017-08-24 16:23:15 -03004188Setting the @option{discard-data} boolean option to @var{on}
4189indicates that file contents can be destroyed when QEMU exits,
4190to avoid unnecessarily flushing data to the backing file. Note
4191that @option{discard-data} is only an optimization, and QEMU
4192might not discard file contents if it aborts unexpectedly or is
4193terminated using SIGKILL.
Daniel P. Berrangeb9174d42015-05-13 17:14:03 +01004194
Stefan Hajnoczic7cddce2017-11-28 16:15:28 +00004195The @option{merge} boolean option enables memory merge, also known as
4196MADV_MERGEABLE, so that Kernel Samepage Merging will consider the pages for
4197memory deduplication.
4198
4199Setting the @option{dump} boolean option to @var{off} excludes the memory from
4200core dumps. This feature is also known as MADV_DONTDUMP.
4201
4202The @option{prealloc} boolean option enables memory preallocation.
4203
4204The @option{host-nodes} option binds the memory range to a list of NUMA host
4205nodes.
4206
4207The @option{policy} option sets the NUMA policy to one of the following values:
4208
4209@table @option
4210@item @var{default}
4211default host policy
4212
4213@item @var{preferred}
4214prefer the given host node list for allocation
4215
4216@item @var{bind}
4217restrict memory allocation to the given host node list
4218
4219@item @var{interleave}
4220interleave memory allocations across the given host node list
4221@end table
4222
Haozhong Zhang98376842017-12-11 15:28:04 +08004223The @option{align} option specifies the base address alignment when
4224QEMU mmap(2) @option{mem-path}, and accepts common suffixes, eg
4225@option{2M}. Some backend store specified by @option{mem-path}
4226requires an alignment different than the default one used by QEMU, eg
4227the device DAX /dev/dax0.0 requires 2M alignment rather than 4K. In
4228such cases, users can specify the required alignment via this option.
4229
Junyan Hea4de8552018-07-18 15:48:00 +08004230The @option{pmem} option specifies whether the backing file specified
4231by @option{mem-path} is in host persistent memory that can be accessed
4232using the SNIA NVM programming model (e.g. Intel NVDIMM).
4233If @option{pmem} is set to 'on', QEMU will take necessary operations to
4234guarantee the persistence of its own writes to @option{mem-path}
4235(e.g. in vNVDIMM label emulation and live migration).
Zhang Yi119906af2019-04-22 08:48:48 +08004236Also, we will map the backend-file with MAP_SYNC flag, which ensures the
4237file metadata is in sync for @option{mem-path} in case of host crash
4238or a power failure. MAP_SYNC requires support from both the host kernel
4239(since Linux kernel 4.15) and the filesystem of @option{mem-path} mounted
4240with DAX option.
Junyan Hea4de8552018-07-18 15:48:00 +08004241
Marcel Apfelbaum06329cc2017-12-13 16:37:37 +02004242@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 +00004243
4244Creates a memory backend object, which can be used to back the guest RAM.
4245Memory backend objects offer more control than the @option{-m} option that is
4246traditionally used to define guest RAM. Please refer to
4247@option{memory-backend-file} for a description of the options.
4248
Marc-André Lureau36ea3972018-08-28 17:38:40 +02004249@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 +01004250
4251Creates an anonymous memory file backend object, which allows QEMU to
4252share the memory with an external process (e.g. when using
4253vhost-user). The memory is allocated with memfd and optional
4254sealing. (Linux only)
4255
4256The @option{seal} option creates a sealed-file, that will block
4257further resizing the memory ('on' by default).
4258
4259The @option{hugetlb} option specify the file to be created resides in
4260the hugetlbfs filesystem (since Linux 4.14). Used in conjunction with
4261the @option{hugetlb} option, the @option{hugetlbsize} option specify
4262the hugetlb page size on systems that support multiple hugetlb page
4263sizes (it must be a power of 2 value supported by the system).
4264
4265In some versions of Linux, the @option{hugetlb} option is incompatible
4266with the @option{seal} option (requires at least Linux 4.16).
4267
4268Please refer to @option{memory-backend-file} for a description of the
4269other options.
4270
Marc-André Lureau36ea3972018-08-28 17:38:40 +02004271The @option{share} boolean option is @var{on} by default with memfd.
4272
Daniel P. Berrangeb9174d42015-05-13 17:14:03 +01004273@item -object rng-random,id=@var{id},filename=@var{/dev/random}
4274
4275Creates a random number generator backend which obtains entropy from
4276a device on the host. The @option{id} parameter is a unique ID that
4277will be used to reference this entropy backend from the @option{virtio-rng}
4278device. The @option{filename} parameter specifies which file to obtain
4279entropy from and if omitted defaults to @option{/dev/random}.
4280
4281@item -object rng-egd,id=@var{id},chardev=@var{chardevid}
4282
4283Creates a random number generator backend which obtains entropy from
4284an external daemon running on the host. The @option{id} parameter is
4285a unique ID that will be used to reference this entropy backend from
4286the @option{virtio-rng} device. The @option{chardev} parameter is
4287the unique ID of a character device backend that provides the connection
4288to the RNG daemon.
4289
Daniel P. Berrangee00adf62015-03-13 17:39:26 +00004290@item -object tls-creds-anon,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/cred/dir},verify-peer=@var{on|off}
4291
4292Creates a TLS anonymous credentials object, which can be used to provide
4293TLS support on network backends. The @option{id} parameter is a unique
4294ID which network backends will use to access the credentials. The
4295@option{endpoint} is either @option{server} or @option{client} depending
4296on whether the QEMU network backend that uses the credentials will be
4297acting as a client or as a server. If @option{verify-peer} is enabled
4298(the default) then once the handshake is completed, the peer credentials
4299will be verified, though this is a no-op for anonymous credentials.
4300
4301The @var{dir} parameter tells QEMU where to find the credential
4302files. For server endpoints, this directory may contain a file
4303@var{dh-params.pem} providing diffie-hellman parameters to use
4304for the TLS server. If the file is missing, QEMU will generate
4305a set of DH parameters at startup. This is a computationally
4306expensive operation that consumes random pool entropy, so it is
4307recommended that a persistent set of parameters be generated
4308upfront and saved.
4309
Richard W.M. Jonese1a6dc92018-07-03 09:03:03 +01004310@item -object tls-creds-psk,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/keys/dir}[,username=@var{username}]
4311
4312Creates a TLS Pre-Shared Keys (PSK) credentials object, which can be used to provide
4313TLS support on network backends. The @option{id} parameter is a unique
4314ID which network backends will use to access the credentials. The
4315@option{endpoint} is either @option{server} or @option{client} depending
4316on whether the QEMU network backend that uses the credentials will be
4317acting as a client or as a server. For clients only, @option{username}
4318is the username which will be sent to the server. If omitted
4319it defaults to ``qemu''.
4320
4321The @var{dir} parameter tells QEMU where to find the keys file.
4322It is called ``@var{dir}/keys.psk'' and contains ``username:key''
4323pairs. This file can most easily be created using the GnuTLS
4324@code{psktool} program.
4325
4326For server endpoints, @var{dir} may also contain a file
4327@var{dh-params.pem} providing diffie-hellman parameters to use
4328for the TLS server. If the file is missing, QEMU will generate
4329a set of DH parameters at startup. This is a computationally
4330expensive operation that consumes random pool entropy, so it is
4331recommended that a persistent set of parameters be generated
4332up front and saved.
4333
Christophe Fergeau00e5e9d2017-12-08 15:14:30 +01004334@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 +00004335
4336Creates a TLS anonymous credentials object, which can be used to provide
4337TLS support on network backends. The @option{id} parameter is a unique
4338ID which network backends will use to access the credentials. The
4339@option{endpoint} is either @option{server} or @option{client} depending
4340on whether the QEMU network backend that uses the credentials will be
4341acting as a client or as a server. If @option{verify-peer} is enabled
4342(the default) then once the handshake is completed, the peer credentials
4343will be verified. With x509 certificates, this implies that the clients
4344must be provided with valid client certificates too.
4345
4346The @var{dir} parameter tells QEMU where to find the credential
4347files. For server endpoints, this directory may contain a file
4348@var{dh-params.pem} providing diffie-hellman parameters to use
4349for the TLS server. If the file is missing, QEMU will generate
4350a set of DH parameters at startup. This is a computationally
4351expensive operation that consumes random pool entropy, so it is
4352recommended that a persistent set of parameters be generated
4353upfront and saved.
4354
4355For x509 certificate credentials the directory will contain further files
4356providing the x509 certificates. The certificates must be stored
4357in PEM format, in filenames @var{ca-cert.pem}, @var{ca-crl.pem} (optional),
4358@var{server-cert.pem} (only servers), @var{server-key.pem} (only servers),
4359@var{client-cert.pem} (only clients), and @var{client-key.pem} (only clients).
4360
Daniel P. Berrange1d7b5b42015-10-15 16:14:42 +01004361For the @var{server-key.pem} and @var{client-key.pem} files which
4362contain sensitive private keys, it is possible to use an encrypted
4363version by providing the @var{passwordid} parameter. This provides
4364the ID of a previously created @code{secret} object containing the
4365password for decryption.
4366
Christophe Fergeau00e5e9d2017-12-08 15:14:30 +01004367The @var{priority} parameter allows to override the global default
4368priority used by gnutls. This can be useful if the system administrator
4369needs to use a weaker set of crypto priorities for QEMU without
4370potentially forcing the weakness onto all applications. Or conversely
4371if one wants wants a stronger default for QEMU than for all other
4372applications, they can do this through this parameter. Its format is
4373a gnutls priority string as described at
4374@url{https://gnutls.org/manual/html_node/Priority-Strings.html}.
4375
zhanghailiang338d3f42016-03-01 13:37:02 +08004376@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 +08004377
4378Interval @var{t} can't be 0, this filter batches the packet delivery: all
4379packets arriving in a given interval on netdev @var{netdevid} are delayed
4380until the end of the interval. Interval is in microseconds.
zhanghailiang338d3f42016-03-01 13:37:02 +08004381@option{status} is optional that indicate whether the netfilter is
4382on (enabled) or off (disabled), the default status for netfilter will be 'on'.
Yang Hongyang7dbb11c2015-10-07 11:52:21 +08004383
4384queue @var{all|rx|tx} is an option that can be applied to any netfilter.
4385
4386@option{all}: the filter is attached both to the receive and the transmit
4387 queue of the netdev (default).
4388
4389@option{rx}: the filter is attached to the receive queue of the netdev,
4390 where it will receive packets sent to the netdev.
4391
4392@option{tx}: the filter is attached to the transmit queue of the netdev,
4393 where it will receive packets sent by the netdev.
4394
Zhang Chene2521f02017-07-04 14:53:48 +08004395@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 +08004396
Zhang Chene2521f02017-07-04 14:53:48 +08004397filter-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 +08004398
Zhang Chen00d5c242017-07-04 14:53:49 +08004399@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 +08004400
4401filter-redirector on netdev @var{netdevid},redirect filter's net packet to chardev
Zhang Chen00d5c242017-07-04 14:53:49 +08004402@var{chardevid},and redirect indev's packet to filter.if it has the vnet_hdr_support flag,
4403filter-redirector will redirect packet with vnet_hdr_len.
Zhang Chend46f75b2016-03-17 16:16:26 +08004404Create a filter-redirector we need to differ outdev id from indev id, id can not
4405be the same. we can just use indev or outdev, but at least one of indev or outdev
4406need to be specified.
4407
Zhang Chen4b39bdc2017-07-04 14:53:55 +08004408@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 +08004409
4410Filter-rewriter is a part of COLO project.It will rewrite tcp packet to
4411secondary from primary to keep secondary tcp connection,and rewrite
4412tcp packet to primary from secondary make tcp packet can be handled by
Zhang Chen4b39bdc2017-07-04 14:53:55 +08004413client.if it has the vnet_hdr_support flag, we can parse packet with vnet header.
Zhang Chene6eee8a2016-09-27 10:22:32 +08004414
4415usage:
4416colo secondary:
4417-object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0
4418-object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1
4419-object filter-rewriter,id=rew0,netdev=hn0,queue=all
4420
Changlong Xiec551cd52016-10-11 13:28:32 +08004421@item -object filter-dump,id=@var{id},netdev=@var{dev}[,file=@var{filename}][,maxlen=@var{len}]
Thomas Huthd3e0c032015-10-13 12:40:02 +02004422
4423Dump the network traffic on netdev @var{dev} to the file specified by
4424@var{filename}. At most @var{len} bytes (64k by default) per packet are stored.
4425The file format is libpcap, so it can be analyzed with tools such as tcpdump
4426or Wireshark.
4427
Zhang Chenaa3a7032017-07-04 14:53:52 +08004428@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 +08004429
4430Colo-compare gets packet from primary_in@var{chardevid} and secondary_in@var{chardevid}, than compare primary packet with
4431secondary packet. If the packets are same, we will output primary
4432packet to outdev@var{chardevid}, else we will notify colo-frame
4433do checkpoint and send primary packet to outdev@var{chardevid}.
Zhang Chenaa3a7032017-07-04 14:53:52 +08004434if it has the vnet_hdr_support flag, colo compare will send/recv packet with vnet_hdr_len.
Zhang Chen7dce4e62016-09-27 10:22:26 +08004435
4436we must use it with the help of filter-mirror and filter-redirector.
4437
4438@example
4439
4440primary:
4441-netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown
4442-device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66
4443-chardev socket,id=mirror0,host=3.3.3.3,port=9003,server,nowait
4444-chardev socket,id=compare1,host=3.3.3.3,port=9004,server,nowait
4445-chardev socket,id=compare0,host=3.3.3.3,port=9001,server,nowait
4446-chardev socket,id=compare0-0,host=3.3.3.3,port=9001
4447-chardev socket,id=compare_out,host=3.3.3.3,port=9005,server,nowait
4448-chardev socket,id=compare_out0,host=3.3.3.3,port=9005
4449-object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0
4450-object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out
4451-object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0
4452-object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0
4453
4454secondary:
4455-netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown
4456-device e1000,netdev=hn0,mac=52:a4:00:12:78:66
4457-chardev socket,id=red0,host=3.3.3.3,port=9003
4458-chardev socket,id=red1,host=3.3.3.3,port=9004
4459-object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0
4460-object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1
4461
4462@end example
4463
4464If you want to know the detail of above command line, you can read
4465the colo-compare git log.
4466
Gonglei1653a5f2016-10-28 16:33:23 +08004467@item -object cryptodev-backend-builtin,id=@var{id}[,queues=@var{queues}]
4468
4469Creates a cryptodev backend which executes crypto opreation from
4470the QEMU cipher APIS. The @var{id} parameter is
4471a unique ID that will be used to reference this cryptodev backend from
4472the @option{virtio-crypto} device. The @var{queues} parameter is optional,
4473which specify the queue number of cryptodev backend, the default of
4474@var{queues} is 1.
4475
4476@example
4477
4478 # qemu-system-x86_64 \
4479 [...] \
4480 -object cryptodev-backend-builtin,id=cryptodev0 \
4481 -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \
4482 [...]
4483@end example
4484
Gonglei042cea22018-03-01 21:46:28 +08004485@item -object cryptodev-vhost-user,id=@var{id},chardev=@var{chardevid}[,queues=@var{queues}]
4486
4487Creates a vhost-user cryptodev backend, backed by a chardev @var{chardevid}.
4488The @var{id} parameter is a unique ID that will be used to reference this
4489cryptodev backend from the @option{virtio-crypto} device.
4490The chardev should be a unix domain socket backed one. The vhost-user uses
4491a specifically defined protocol to pass vhost ioctl replacement messages
4492to an application on the other end of the socket.
4493The @var{queues} parameter is optional, which specify the queue number
4494of cryptodev backend for multiqueue vhost-user, the default of @var{queues} is 1.
4495
4496@example
4497
4498 # qemu-system-x86_64 \
4499 [...] \
4500 -chardev socket,id=chardev0,path=/path/to/socket \
4501 -object cryptodev-vhost-user,id=cryptodev0,chardev=chardev0 \
4502 -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \
4503 [...]
4504@end example
4505
Daniel P. Berrangeac1d8872015-10-14 09:58:38 +01004506@item -object secret,id=@var{id},data=@var{string},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}]
4507@item -object secret,id=@var{id},file=@var{filename},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}]
4508
4509Defines a secret to store a password, encryption key, or some other sensitive
4510data. The sensitive data can either be passed directly via the @var{data}
4511parameter, or indirectly via the @var{file} parameter. Using the @var{data}
4512parameter is insecure unless the sensitive data is encrypted.
4513
4514The sensitive data can be provided in raw format (the default), or base64.
4515When encoded as JSON, the raw format only supports valid UTF-8 characters,
4516so base64 is recommended for sending binary data. QEMU will convert from
4517which ever format is provided to the format it needs internally. eg, an
4518RBD password can be provided in raw format, even though it will be base64
4519encoded when passed onto the RBD sever.
4520
4521For added protection, it is possible to encrypt the data associated with
4522a secret using the AES-256-CBC cipher. Use of encryption is indicated
4523by providing the @var{keyid} and @var{iv} parameters. The @var{keyid}
4524parameter provides the ID of a previously defined secret that contains
4525the AES-256 decryption key. This key should be 32-bytes long and be
4526base64 encoded. The @var{iv} parameter provides the random initialization
4527vector used for encryption of this particular secret and should be a
Daniel P. Berrange69c0b272016-04-04 10:33:55 +01004528base64 encrypted string of the 16-byte IV.
Daniel P. Berrangeac1d8872015-10-14 09:58:38 +01004529
4530The simplest (insecure) usage is to provide the secret inline
4531
4532@example
4533
4534 # $QEMU -object secret,id=sec0,data=letmein,format=raw
4535
4536@end example
4537
4538The simplest secure usage is to provide the secret via a file
4539
Eric Blakeb43671f2017-07-03 13:09:50 -05004540 # printf "letmein" > mypasswd.txt
Daniel P. Berrangeac1d8872015-10-14 09:58:38 +01004541 # $QEMU -object secret,id=sec0,file=mypasswd.txt,format=raw
4542
4543For greater security, AES-256-CBC should be used. To illustrate usage,
4544consider the openssl command line tool which can encrypt the data. Note
4545that when encrypting, the plaintext must be padded to the cipher block
4546size (32 bytes) using the standard PKCS#5/6 compatible padding algorithm.
4547
4548First a master key needs to be created in base64 encoding:
4549
4550@example
4551 # openssl rand -base64 32 > key.b64
4552 # KEY=$(base64 -d key.b64 | hexdump -v -e '/1 "%02X"')
4553@end example
4554
4555Each secret to be encrypted needs to have a random initialization vector
4556generated. These do not need to be kept secret
4557
4558@example
4559 # openssl rand -base64 16 > iv.b64
4560 # IV=$(base64 -d iv.b64 | hexdump -v -e '/1 "%02X"')
4561@end example
4562
4563The secret to be defined can now be encrypted, in this case we're
4564telling openssl to base64 encode the result, but it could be left
4565as raw bytes if desired.
4566
4567@example
Eric Blakeb43671f2017-07-03 13:09:50 -05004568 # SECRET=$(printf "letmein" |
Daniel P. Berrangeac1d8872015-10-14 09:58:38 +01004569 openssl enc -aes-256-cbc -a -K $KEY -iv $IV)
4570@end example
4571
4572When launching QEMU, create a master secret pointing to @code{key.b64}
4573and specify that to be used to decrypt the user password. Pass the
4574contents of @code{iv.b64} to the second secret
4575
4576@example
4577 # $QEMU \
4578 -object secret,id=secmaster0,format=base64,file=key.b64 \
4579 -object secret,id=sec0,keyid=secmaster0,format=base64,\
4580 data=$SECRET,iv=$(<iv.b64)
4581@end example
4582
Brijesh Singha9b49422018-03-08 06:48:41 -06004583@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}]
4584
4585Create a Secure Encrypted Virtualization (SEV) guest object, which can be used
4586to provide the guest memory encryption support on AMD processors.
4587
4588When memory encryption is enabled, one of the physical address bit (aka the
4589C-bit) is utilized to mark if a memory page is protected. The @option{cbitpos}
4590is used to provide the C-bit position. The C-bit position is Host family dependent
4591hence user must provide this value. On EPYC, the value should be 47.
4592
4593When memory encryption is enabled, we loose certain bits in physical address space.
4594The @option{reduced-phys-bits} is used to provide the number of bits we loose in
4595physical address space. Similar to C-bit, the value is Host family dependent.
4596On EPYC, the value should be 5.
4597
4598The @option{sev-device} provides the device file to use for communicating with
4599the SEV firmware running inside AMD Secure Processor. The default device is
4600'/dev/sev'. If hardware supports memory encryption then /dev/sev devices are
4601created by CCP driver.
4602
4603The @option{policy} provides the guest policy to be enforced by the SEV firmware
4604and restrict what configuration and operational commands can be performed on this
4605guest by the hypervisor. The policy should be provided by the guest owner and is
4606bound to the guest and cannot be changed throughout the lifetime of the guest.
4607The default is 0.
4608
4609If guest @option{policy} allows sharing the key with another SEV guest then
4610@option{handle} can be use to provide handle of the guest from which to share
4611the key.
4612
4613The @option{dh-cert-file} and @option{session-file} provides the guest owner's
4614Public Diffie-Hillman key defined in SEV spec. The PDH and session parameters
4615are used for establishing a cryptographic session with the guest owner to
4616negotiate keys used for attestation. The file must be encoded in base64.
4617
4618e.g to launch a SEV guest
4619@example
4620 # $QEMU \
4621 ......
4622 -object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=5 \
4623 -machine ...,memory-encryption=sev0
4624 .....
4625
4626@end example
Daniel P. Berrangéfb5c4eb2018-05-02 15:40:33 +01004627
4628
4629@item -object authz-simple,id=@var{id},identity=@var{string}
4630
4631Create an authorization object that will control access to network services.
4632
4633The @option{identity} parameter is identifies the user and its format
4634depends on the network service that authorization object is associated
4635with. For authorizing based on TLS x509 certificates, the identity must
4636be the x509 distinguished name. Note that care must be taken to escape
4637any commas in the distinguished name.
4638
4639An example authorization object to validate a x509 distinguished name
4640would look like:
4641@example
4642 # $QEMU \
4643 ...
4644 -object 'authz-simple,id=auth0,identity=CN=laptop.example.com,,O=Example Org,,L=London,,ST=London,,C=GB' \
4645 ...
4646@end example
4647
4648Note the use of quotes due to the x509 distinguished name containing
4649whitespace, and escaping of ','.
4650
Daniel P. Berrangé55d86982018-05-11 12:19:59 +01004651@item -object authz-listfile,id=@var{id},filename=@var{path},refresh=@var{yes|no}
4652
4653Create an authorization object that will control access to network services.
4654
4655The @option{filename} parameter is the fully qualified path to a file
4656containing the access control list rules in JSON format.
4657
4658An example set of rules that match against SASL usernames might look
4659like:
4660
4661@example
4662 @{
4663 "rules": [
4664 @{ "match": "fred", "policy": "allow", "format": "exact" @},
4665 @{ "match": "bob", "policy": "allow", "format": "exact" @},
4666 @{ "match": "danb", "policy": "deny", "format": "glob" @},
4667 @{ "match": "dan*", "policy": "allow", "format": "exact" @},
4668 ],
4669 "policy": "deny"
4670 @}
4671@end example
4672
4673When checking access the object will iterate over all the rules and
4674the first rule to match will have its @option{policy} value returned
4675as the result. If no rules match, then the default @option{policy}
4676value is returned.
4677
4678The rules can either be an exact string match, or they can use the
4679simple UNIX glob pattern matching to allow wildcards to be used.
4680
4681If @option{refresh} is set to true the file will be monitored
4682and automatically reloaded whenever its content changes.
4683
4684As with the @code{authz-simple} object, the format of the identity
4685strings being matched depends on the network service, but is usually
4686a TLS x509 distinguished name, or a SASL username.
4687
4688An example authorization object to validate a SASL username
4689would look like:
4690@example
4691 # $QEMU \
4692 ...
4693 -object authz-simple,id=auth0,filename=/etc/qemu/vnc-sasl.acl,refresh=yes
4694 ...
4695@end example
4696
Daniel P. Berrange8953caf2016-07-27 14:13:56 +01004697@item -object authz-pam,id=@var{id},service=@var{string}
4698
4699Create an authorization object that will control access to network services.
4700
4701The @option{service} parameter provides the name of a PAM service to use
4702for authorization. It requires that a file @code{/etc/pam.d/@var{service}}
4703exist to provide the configuration for the @code{account} subsystem.
4704
4705An example authorization object to validate a TLS x509 distinguished
4706name would look like:
4707
4708@example
4709 # $QEMU \
4710 ...
4711 -object authz-pam,id=auth0,service=qemu-vnc
4712 ...
4713@end example
4714
4715There would then be a corresponding config file for PAM at
4716@code{/etc/pam.d/qemu-vnc} that contains:
4717
4718@example
4719account requisite pam_listfile.so item=user sense=allow \
4720 file=/etc/qemu/vnc.allow
4721@end example
4722
4723Finally the @code{/etc/qemu/vnc.allow} file would contain
4724the list of x509 distingished names that are permitted
4725access
4726
4727@example
4728CN=laptop.example.com,O=Example Home,L=London,ST=London,C=GB
4729@end example
4730
4731
Daniel P. Berrangeb9174d42015-05-13 17:14:03 +01004732@end table
4733
4734ETEXI
4735
4736
Stefan Weil3dbf2c72010-01-16 18:19:44 +01004737HXCOMM This is the last statement. Insert new options before this line!
4738STEXI
4739@end table
4740ETEXI