1QEMU(1)                              QEMU                              QEMU(1)
2
3
4

NAME

6       qemu - QEMU User Documentation
7

SYNOPSIS

9          qemu-system-x86_64 [options] [disk_image]
10

DESCRIPTION

12       The QEMU PC System emulator simulates the following peripherals:
13
14       · i440FX host PCI bridge and PIIX3 PCI to ISA bridge
15
16       · Cirrus  CLGD  5446  PCI  VGA  card  or dummy VGA card with Bochs VESA
17         extensions (hardware level, including all non standard modes).
18
19       · PS/2 mouse and keyboard
20
21       · 2 PCI IDE interfaces with hard disk and CD-ROM support
22
23       · Floppy disk
24
25       · PCI and ISA network adapters
26
27       · Serial ports
28
29       · IPMI BMC, either and internal or external one
30
31       · Creative SoundBlaster 16 sound card
32
33       · ENSONIQ AudioPCI ES1370 sound card
34
35       · Intel 82801AA AC97 Audio compatible sound card
36
37       · Intel HD Audio Controller and HDA codec
38
39       · Adlib (OPL2) - Yamaha YM3812 compatible chip
40
41       · Gravis Ultrasound GF1 sound card
42
43       · CS4231A compatible sound card
44
45       · PC speaker
46
47       · PCI UHCI, OHCI, EHCI or XHCI USB controller  and  a  virtual  USB-1.1
48         hub.
49
50       SMP is supported with up to 255 CPUs.
51
52       QEMU  uses  the  PC  BIOS from the Seabios project and the Plex86/Bochs
53       LGPL VGA BIOS.
54
55       QEMU uses YM3812 emulation by Tatsuyuki Satoh.
56
57       QEMU uses GUS emulation (GUSEMU32 http://www.deinmeister.de/gusemu/) by
58       Tibor "TS" Schütz.
59
60       Note  that,  by  default,  GUS shares IRQ(7) with parallel ports and so
61       QEMU must be told to not have parallel ports to have working GUS.
62
63          qemu_system-x86_64 dos.img -device gus -parallel none
64
65       Alternatively:
66
67          qemu_system-x86_64 dos.img -device gus,irq=5
68
69       Or some other unclaimed IRQ.
70
71       CS4231A is the chip used in Windows Sound System and GUSMAX products
72
73       The PC speaker audio device can be configured using the  pcspk-audiodev
74       machine property, i.e.
75
76          qemu_system-x86_64 some.img -audiodev <backend>,id=<name> -machine pcspk-audiodev=<name>
77

OPTIONS

79       disk_image  is  a raw hard disk image for IDE hard disk 0. Some targets
80       do not need a disk image.
81
82   Standard options
83       -h     Display help and exit
84
85       -version
86              Display version information and exit
87
88       -machine [type=]name[,prop=value[,...]]
89              Select the emulated machine by name. Use -machine help  to  list
90              available machines.
91
92              For  architectures  which aim to support live migration compati‐
93              bility across releases, each release will introduce a  new  ver‐
94              sioned  machine  type. For example, the 2.8.0 release introduced
95              machine  types  "pc-i440fx-2.8"   and   "pc-q35-2.8"   for   the
96              x86_64/i686 architectures.
97
98              To  allow  live  migration of guests from QEMU version 2.8.0, to
99              QEMU  version  2.9.0,  the  2.9.0  version  must   support   the
100              "pc-i440fx-2.8"  and  "pc-q35-2.8"  machines too. To allow users
101              live migrating VMs to skip multiple intermediate  releases  when
102              upgrading,  new releases of QEMU will support machine types from
103              many previous versions.
104
105              Supported machine properties are:
106
107              accel=accels1[:accels2[:...]]
108                     This is used to enable an accelerator. Depending  on  the
109                     target  architecture, kvm, xen, hax, hvf, whpx or tcg can
110                     be available.  By default, tcg is used. If there is  more
111                     than  one  accelerator specified, the next one is used if
112                     the previous one fails to initialize.
113
114              vmport=on|off|auto
115                     Enables emulation of VMWare IO  port,  for  vmmouse  etc.
116                     auto  says  to  select  the  value  based  on  accel. For
117                     accel=xen the default is off otherwise the default is on.
118
119              dump-guest-core=on|off
120                     Include guest memory in a core dump. The default is on.
121
122              mem-merge=on|off
123                     Enables or disables memory merge support.  This  feature,
124                     when  supported by the host, de-duplicates identical mem‐
125                     ory pages among VMs instances (enabled by default).
126
127              aes-key-wrap=on|off
128                     Enables or disables AES key wrapping support on  s390-ccw
129                     hosts.   This  feature controls whether AES wrapping keys
130                     will be created to allow execution of  AES  cryptographic
131                     functions. The default is on.
132
133              dea-key-wrap=on|off
134                     Enables  or disables DEA key wrapping support on s390-ccw
135                     hosts.  This feature controls whether DEA  wrapping  keys
136                     will  be  created to allow execution of DEA cryptographic
137                     functions. The default is on.
138
139              nvdimm=on|off
140                     Enables or disables NVDIMM support. The default is off.
141
142              enforce-config-section=on|off
143                     If enforce-config-section is set to on,  force  migration
144                     code   to   send   configuration   section  even  if  the
145                     machine-type sets the migration.send-configuration  prop‐
146                     erty  to  off. NOTE: this parameter is deprecated. Please
147                     use -global migration.send-configuration=on|off instead.
148
149              memory-encryption=
150                     Memory encryption object to use. The default is none.
151
152              hmat=on|off
153                     Enables or disables ACPI Heterogeneous  Memory  Attribute
154                     Table (HMAT) support. The default is off.
155
156       -cpu model
157              Select  CPU  model  (-cpu  help  for list and additional feature
158              selection)
159
160       -accel name[,prop=value[,...]]
161              This is used to enable an accelerator. Depending on  the  target
162              architecture,  kvm, xen, hax, hvf, whpx or tcg can be available.
163              By default, tcg is used. If there is more than  one  accelerator
164              specified,  the  next  one  is used if the previous one fails to
165              initialize.
166
167              igd-passthru=on|off
168                     When Xen is in use, this option  controls  whether  Intel
169                     integrated  graphics devices can be passed through to the
170                     guest (default=off)
171
172              kernel-irqchip=on|off|split
173                     Controls KVM in-kernel irqchip support.  The  default  is
174                     full  acceleration  of the interrupt controllers. On x86,
175                     split irqchip reduces the kernel  attack  surface,  at  a
176                     performance  cost  for  non-MSI interrupts. Disabling the
177                     in-kernel irqchip completely is  not  recommended  except
178                     for debugging purposes.
179
180              kvm-shadow-mem=size
181                     Defines the size of the KVM shadow MMU.
182
183              tb-size=n
184                     Controls  the  size (in MiB) of the TCG translation block
185                     cache.
186
187              thread=single|multi
188                     Controls  number  of  TCG  threads.  When  the   TCG   is
189                     multi-threaded there will be one thread per vCPU therefor
190                     taking advantage of additional host cores. The default is
191                     to  enable  multi-threading  where  both the back-end and
192                     front-ends support it and no  incompatible  TCG  features
193                     have been enabled (e.g.  icount/replay).
194
195       -smp        [cpus=]n[,cores=cores][,threads=threads][,dies=dies][,sock‐
196       ets=sockets][,maxcpus=maxcpus]
197              Simulate an SMP system with n CPUs. On the PC target, up to  255
198              CPUs  are  supported. On Sparc32 target, Linux limits the number
199              of usable CPUs to 4. For the PC target, the number of cores  per
200              die,  the  number  of  threads per cores, the number of dies per
201              packages and the total number of sockets can be specified. Miss‐
202              ing  values  will  be  computed.  If  any on the three values is
203              given, the total number of CPUs n can be omitted. maxcpus speci‐
204              fies the maximum number of hotpluggable CPUs.
205
206       -numa  node[,mem=size][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initia‐
207       tor=initiator]
208
209
210       -numa node[,memdev=id][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initia‐
211       tor=initiator]
212
213
214       -numa dist,src=source,dst=destination,val=distance
215
216
217       -numa cpu,node-id=node[,socket-id=x][,core-id=y][,thread-id=z]
218
219
220       -numa              hmat-lb,initiator=node,target=node,hierarchy=hierar‐
221       chy,data-type=tpye[,latency=lat][,bandwidth=bw]
222
223
224       -numa        hmat-cache,node-id=node,size=size,level=level[,associativ‐
225       ity=str][,policy=str][,line=size]
226              Define  a NUMA node and assign RAM and VCPUs to it. Set the NUMA
227              distance from a source node to a destination node. Set the  ACPI
228              Heterogeneous Memory Attributes for the given nodes.
229
230              Legacy  VCPU  assignment  uses  'cpus' option where firstcpu and
231              lastcpu are CPU indexes. Each 'cpus' option represent a contigu‐
232              ous  range  of CPU indexes (or a single VCPU if lastcpu is omit‐
233              ted). A non-contiguous set of VCPUs can be represented  by  pro‐
234              viding  multiple  'cpus'  options.  If  'cpus' is omitted on all
235              nodes, VCPUs are automatically split between them.
236
237              For example, the following option assigns VCPUs 0, 1, 2 and 5 to
238              a NUMA node:
239
240                 -numa node,cpus=0-2,cpus=5
241
242              'cpu'  option  is  a new alternative to 'cpus' option which uses
243              'socket-id|core-id|thread-id' properties to assign  CPU  objects
244              to  a  node  using topology layout properties of CPU. The set of
245              properties is machine specific,  and  depends  on  used  machine
246              type/'smp' options. It could be queried with 'hotpluggable-cpus'
247              monitor command. 'node-id' property specifies node to which  CPU
248              object  will  be assigned, it's required for node to be declared
249              with 'node' option before it's used with 'cpu' option.
250
251              For example:
252
253                 -M pc \
254                 -smp 1,sockets=2,maxcpus=2 \
255                 -numa node,nodeid=0 -numa node,nodeid=1 \
256                 -numa cpu,node-id=0,socket-id=0 -numa cpu,node-id=1,socket-id=1
257
258              Legacy 'mem' assigns a given RAM amount to a node (not supported
259              for  5.1  and  newer machine types). 'memdev' assigns RAM from a
260              given memory backend device to a node. If 'mem' and 'memdev' are
261              omitted in all nodes, RAM is split equally between them.
262
263              'mem'  and 'memdev' are mutually exclusive.  Furthermore, if one
264              node uses 'memdev', all of them have to use it.
265
266              'initiator' is an additional option that points to an  initiator
267              NUMA  node  that  has  best  performance  (the lowest latency or
268              largest bandwidth) to this NUMA node. Note that this option  can
269              be set only when the machine property 'hmat' is set to 'on'.
270
271              Following  example  creates  a machine with 2 NUMA nodes, node 0
272              has CPU. node 1 has only memory, and its initiator  is  node  0.
273              Note  that  because  node 0 has CPU, by default the initiator of
274              node 0 is itself and must be itself.
275
276                 -machine hmat=on \
277                 -m 2G,slots=2,maxmem=4G \
278                 -object memory-backend-ram,size=1G,id=m0 \
279                 -object memory-backend-ram,size=1G,id=m1 \
280                 -numa node,nodeid=0,memdev=m0 \
281                 -numa node,nodeid=1,memdev=m1,initiator=0 \
282                 -smp 2,sockets=2,maxcpus=2  \
283                 -numa cpu,node-id=0,socket-id=0 \
284                 -numa cpu,node-id=0,socket-id=1
285
286              source and destination are NUMA node IDs. distance is  the  NUMA
287              distance from source to destination. The distance from a node to
288              itself is always 10. If any pair of nodes is given  a  distance,
289              then all pairs must be given distances. Although, when distances
290              are only given in one direction for each pair of nodes, then the
291              distances in the opposite directions are assumed to be the same.
292              If, however, an asymmetrical pair of distances is given for even
293              one  node  pair,  then  all node pairs must be provided distance
294              values for both directions, even when they are symmetrical. When
295              a node is unreachable from another node, set the pair's distance
296              to 255.
297
298              Note that the -numa option doesn't allocate any of the specified
299              resources,  it  just  assigns  existing resources to NUMA nodes.
300              This means that one still has to use the  -m,  -smp  options  to
301              allocate RAM and VCPUs respectively.
302
303              Use  'hmat-lb'  to  set  System  Locality  Latency and Bandwidth
304              Information between initiator and target NUMA nodes in ACPI Het‐
305              erogeneous  Attribute  Memory  Table (HMAT). Initiator NUMA node
306              can create memory requests, usually it has one or  more  proces‐
307              sors.  Target NUMA node contains addressable memory.
308
309              In  'hmat-lb'  option,  node are NUMA node IDs. hierarchy is the
310              memory hierarchy of the target NUMA node: if hierarchy is  'mem‐
311              ory',  the structure represents the memory performance; if hier‐
312              archy is 'first-level|second-level|third-level', this  structure
313              represents aggregated performance of memory side caches for each
314              domain. type of 'data-type' is type of data represented by  this
315              structure  instance:  if 'hierarchy' is 'memory', 'data-type' is
316              'access|read|write' latency or 'access|read|write' bandwidth  of
317              the   target   memory;   if   'hierarchy'  is  'first-level|sec‐
318              ond-level|third-level', 'data-type' is  'access|read|write'  hit
319              latency  or 'access|read|write' hit bandwidth of the target mem‐
320              ory side cache.
321
322              lat is latency value in nanoseconds. bw is bandwidth value,  the
323              possible value and units are NUM[M|G|T], mean that the bandwidth
324              value are NUM byte per second (or MB/s, GB/s or  TB/s  depending
325              on  used  suffix). Note that if latency or bandwidth value is 0,
326              means the corresponding latency or bandwidth information is  not
327              provided.
328
329              In  'hmat-cache'  option,  node-id  is the NUMA-id of the memory
330              belongs. size is the size of memory side cache in  bytes.  level
331              is  the  cache  level described in this structure, note that the
332              cache level 0 should  not  be  used  with  'hmat-cache'  option.
333              associativity  is the cache associativity, the possible value is
334              'none/direct(direct-mapped)/complex(complex  cache   indexing)'.
335              policy  is  the  write  policy.  line  is the cache Line size in
336              bytes.
337
338              For example, the following options describe 2 NUMA nodes. Node 0
339              has  2  cpus and a ram, node 1 has only a ram. The processors in
340              node 0 access memory in node 0 with  access-latency  5  nanosec‐
341              onds,  access-bandwidth is 200 MB/s; The processors in NUMA node
342              0 access memory in NUMA node 1 with access-latency  10  nanosec‐
343              onds,  access-bandwidth  is  100 MB/s. And for memory side cache
344              information, NUMA node 0 and 1 both have 1 level  memory  cache,
345              size  is  10KB,  policy  is write-back, the cache Line size is 8
346              bytes:
347
348                 -machine hmat=on \
349                 -m 2G \
350                 -object memory-backend-ram,size=1G,id=m0 \
351                 -object memory-backend-ram,size=1G,id=m1 \
352                 -smp 2 \
353                 -numa node,nodeid=0,memdev=m0 \
354                 -numa node,nodeid=1,memdev=m1,initiator=0 \
355                 -numa cpu,node-id=0,socket-id=0 \
356                 -numa cpu,node-id=0,socket-id=1 \
357                 -numa hmat-lb,initiator=0,target=0,hierarchy=memory,data-type=access-latency,latency=5 \
358                 -numa hmat-lb,initiator=0,target=0,hierarchy=memory,data-type=access-bandwidth,bandwidth=200M \
359                 -numa hmat-lb,initiator=0,target=1,hierarchy=memory,data-type=access-latency,latency=10 \
360                 -numa hmat-lb,initiator=0,target=1,hierarchy=memory,data-type=access-bandwidth,bandwidth=100M \
361                 -numa hmat-cache,node-id=0,size=10K,level=1,associativity=direct,policy=write-back,line=8 \
362                 -numa hmat-cache,node-id=1,size=10K,level=1,associativity=direct,policy=write-back,line=8
363
364       -add-fd fd=fd,set=set[,opaque=opaque]
365              Add a file descriptor to an fd set. Valid options are:
366
367              fd=fd  This option defines the file descriptor of which a dupli‐
368                     cate  is  added  to fd set. The file descriptor cannot be
369                     stdin, stdout, or stderr.
370
371              set=set
372                     This option defines the ID of the fd set to add the  file
373                     descriptor to.
374
375              opaque=opaque
376                     This  option  defines a free-form string that can be used
377                     to describe fd.
378
379              You can open an image using pre-opened file descriptors from  an
380              fd set:
381
382                 qemu-system-x86_64  -add-fd fd=3,set=2,opaque="rdwr:/path/to/file"  -add-fd fd=4,set=2,opaque="rdonly:/path/to/file"  -drive file=/dev/fdset/2,index=0,media=disk
383
384       -set group.id.arg=value
385              Set parameter arg for item id of type group
386
387       -global driver.prop=value
388
389
390       -global driver=driver,property=property,value=value
391              Set default value of driver's property prop to value, e.g.:
392
393                 qemu_system-x86_64 -global ide-hd.physical_block_size=4096 disk-image.img
394
395              In  particular,  you  can  use this to set driver properties for
396              devices which are created automatically by the machine model. To
397              create a device which is not created automatically and set prop‐
398              erties on it, use -device.
399
400              -global   driver.prop=value    is    shorthand    for    -global
401              driver=driver,property=prop,value=value.   The  longhand  syntax
402              works even when driver contains a dot.
403
404       -boot
405       [order=drives][,once=drives][,menu=on|off][,splash=sp_name][,splash-time=sp_time][,reboot-time‐
406       out=rb_timeout][,strict=on|off]
407              Specify boot order drives as a string of  drive  letters.  Valid
408              drive  letters  depend  on  the  target architecture. The x86 PC
409              uses: a, b (floppy 1 and 2),  c  (first  hard  disk),  d  (first
410              CD-ROM),  n-p  (Etherboot  from  network adapter 1-4), hard disk
411              boot is the default.  To apply a particular boot order  only  on
412              the  first  startup, specify it via once. Note that the order or
413              once parameter should not be used together  with  the  bootindex
414              property of devices, since the firmware implementations normally
415              do not support both at the same time.
416
417              Interactive boot menus/prompts can be enabled via menu=on as far
418              as  firmware/BIOS  supports them. The default is non-interactive
419              boot.
420
421              A splash picture could be passed to bios, enabling user to  show
422              it  as logo, when option splash=sp_name is given and menu=on, If
423              firmware/BIOS supports them. Currently Seabios  for  X86  system
424              support  it. limitation: The splash file could be a jpeg file or
425              a BMP file in 24 BPP format(true color). The  resolution  should
426              be  supported  by  the SVGA mode, so the recommended is 320x240,
427              640x480, 800x640.
428
429              A timeout could be passed to bios, guest will pause for rb_time‐
430              out  ms  when  boot  failed, then reboot. If rb_timeout is '-1',
431              guest will not reboot, qemu passes '-1' to bios by default. Cur‐
432              rently Seabios for X86 system support it.
433
434              Do  strict  boot  via strict=on as far as firmware/BIOS supports
435              it. This only effects when boot priority is changed by bootindex
436              options. The default is non-strict boot.
437
438                 # try to boot from network first, then from hard disk
439                 qemu_system-x86_64 -boot order=nc
440                 # boot from CD-ROM first, switch back to default order after reboot
441                 qemu_system-x86_64 -boot once=d
442                 # boot with a splash picture for 5 seconds.
443                 qemu_system-x86_64 -boot menu=on,splash=/root/boot.bmp,splash-time=5000
444
445              Note:  The  legacy  format '-boot drives' is still supported but
446              its use is discouraged as it may be  removed  from  future  ver‐
447              sions.
448
449       -m [size=]megs[,slots=n,maxmem=size]
450              Sets  guest  startup  RAM size to megs megabytes. Default is 128
451              MiB.  Optionally, a suffix of "M" or "G" can be used to  signify
452              a  value  in  megabytes or gigabytes respectively. Optional pair
453              slots, maxmem could be used to set amount of hotpluggable memory
454              slots  and  maximum  amount  of memory. Note that maxmem must be
455              aligned to the page size.
456
457              For example, the following command-line sets the  guest  startup
458              RAM  size  to  1GB, creates 3 slots to hotplug additional memory
459              and sets the maximum memory the guest can reach to 4GB:
460
461                 qemu-system-x86_64 -m 1G,slots=3,maxmem=4G
462
463              If slots and maxmem are not specified, memory hotplug  won't  be
464              enabled and the guest startup RAM will never increase.
465
466       -mem-path path
467              Allocate guest RAM from a temporarily created file in path.
468
469       -mem-prealloc
470              Preallocate memory when using -mem-path.
471
472       -k language
473              Use  keyboard  layout language (for example fr for French). This
474              option is only needed where it is not easy to get  raw  PC  key‐
475              codes  (e.g.  on  Macs,  with  some X11 servers or with a VNC or
476              curses display). You don't normally need to use it  on  PC/Linux
477              or PC/Windows hosts.
478
479              The available layouts are:
480
481                 ar  de-ch  es  fo     fr-ca  hu  ja  mk     no  pt-br  sv
482                 da  en-gb  et  fr     fr-ch  is  lt  nl     pl  ru     th
483                 de  en-us  fi  fr-be  hr     it  lv  nl-be  pt  sl     tr
484
485              The default is en-us.
486
487       -audio-help
488              Will  show  the  -audiodev equivalent of the currently specified
489              (deprecated) environment variables.
490
491       -audiodev [driver=]driver,id=id[,prop[=value][,...]]
492              Adds a new audio backend driver  identified  by  id.  There  are
493              global  and  driver  specific properties. Some values can be set
494              differently for input and output, they're marked  with  in|out..
495              You  can  set the input's property with in.prop and the output's
496              property with out.prop. For example:
497
498                 -audiodev alsa,id=example,in.frequency=44110,out.frequency=8000
499                 -audiodev alsa,id=example,out.channels=1 # leaves in.channels unspecified
500
501              NOTE: parameter validation is known to be  incomplete,  in  many
502              cases specifying an invalid option causes QEMU to print an error
503              message and continue emulation without sound.
504
505              Valid global options are:
506
507              id=identifier
508                     Identifies the audio backend.
509
510              timer-period=period
511                     Sets the timer period used  by  the  audio  subsystem  in
512                     microseconds. Default is 10000 (10 ms).
513
514              in|out.mixing-engine=on|off
515                     Use  QEMU's  mixing engine to mix all streams inside QEMU
516                     and convert audio formats when not supported by the back‐
517                     end.  When off, fixed-settings must be off too. Note that
518                     disabling this option means  that  the  selected  backend
519                     must  support multiple streams and the audio formats used
520                     by the virtual cards, otherwise you'll get no sound. It's
521                     not recommended to disable this option unless you want to
522                     use 5.1 or 7.1 audio, as mixing engine only supports mono
523                     and stereo audio. Default is on.
524
525              in|out.fixed-settings=on|off
526                     Use  fixed  settings  for  host  audio. When off, it will
527                     change based on how the guest opens the  sound  card.  In
528                     this  case  you  must  not specify frequency, channels or
529                     format. Default is on.
530
531              in|out.frequency=frequency
532                     Specify the frequency to use when  using  fixed-settings.
533                     Default is 44100Hz.
534
535              in|out.channels=channels
536                     Specify   the  number  of  channels  to  use  when  using
537                     fixed-settings.  Default is 2 (stereo).
538
539              in|out.format=format
540                     Specify the sample format to use  when  using  fixed-set‐
541                     tings.   Valid  values  are:  s8, s16, s32, u8, u16, u32,
542                     f32. Default is s16.
543
544              in|out.voices=voices
545                     Specify the number of voices to use. Default is 1.
546
547              in|out.buffer-length=usecs
548                     Sets the size of the buffer in microseconds.
549
550       -audiodev none,id=id[,prop[=value][,...]]
551              Creates a dummy backend that discards all outputs. This  backend
552              has no backend specific properties.
553
554       -audiodev alsa,id=id[,prop[=value][,...]]
555              Creates  backend  using the ALSA. This backend is only available
556              on Linux.
557
558              ALSA specific options are:
559
560              in|out.dev=device
561                     Specify the ALSA device to use for input  and/or  output.
562                     Default is default.
563
564              in|out.period-length=usecs
565                     Sets the period length in microseconds.
566
567              in|out.try-poll=on|off
568                     Attempt to use poll mode with the device. Default is on.
569
570              threshold=threshold
571                     Threshold (in microseconds) when playback starts. Default
572                     is 0.
573
574       -audiodev coreaudio,id=id[,prop[=value][,...]]
575              Creates a backend using Apple's Core Audio. This backend is only
576              available on Mac OS and only supports playback.
577
578              Core Audio specific options are:
579
580              in|out.buffer-count=count
581                     Sets the count of the buffers.
582
583       -audiodev dsound,id=id[,prop[=value][,...]]
584              Creates a backend using Microsoft's DirectSound. This backend is
585              only available on Windows and only supports playback.
586
587              DirectSound specific options are:
588
589              latency=usecs
590                     Add extra usecs microseconds latency to playback. Default
591                     is 10000 (10 ms).
592
593       -audiodev oss,id=id[,prop[=value][,...]]
594              Creates  a  backend using OSS. This backend is available on most
595              Unix-like systems.
596
597              OSS specific options are:
598
599              in|out.dev=device
600                     Specify the file name of the OSS device to  use.  Default
601                     is /dev/dsp.
602
603              in|out.buffer-count=count
604                     Sets the count of the buffers.
605
606              in|out.try-poll=on|of
607                     Attempt to use poll mode with the device. Default is on.
608
609              try-mmap=on|off
610                     Try using memory mapped device access. Default is off.
611
612              exclusive=on|off
613                     Open  the  device  in  exclusive mode (vmix won't work in
614                     this case). Default is off.
615
616              dsp-policy=policy
617                     Sets the timing policy (between 0 and 10,  where  smaller
618                     number  means  smaller latency but higher CPU usage). Use
619                     -1 to use buffer  sizes  specified  by  buffer  and  buf‐
620                     fer-count.  This option is ignored if you do not have OSS
621                     4. Default is 5.
622
623       -audiodev pa,id=id[,prop[=value][,...]]
624              Creates a backend using PulseAudio. This backend is available on
625              most systems.
626
627              PulseAudio specific options are:
628
629              server=server
630                     Sets the PulseAudio server to connect to.
631
632              in|out.name=sink
633                     Use the specified source/sink for recording/playback.
634
635              in|out.latency=usecs
636                     Desired  latency  in  microseconds. The PulseAudio server
637                     will try to honor this value but actual latencies may  be
638                     lower or higher.
639
640       -audiodev sdl,id=id[,prop[=value][,...]]
641              Creates  a  backend using SDL. This backend is available on most
642              systems, but you should use your platform's  native  backend  if
643              possible. This backend has no backend specific properties.
644
645       -audiodev spice,id=id[,prop[=value][,...]]
646              Creates  a  backend that sends audio through SPICE. This backend
647              requires -spice and automatically selected in that case, so usu‐
648              ally  you  can  ignore  this option. This backend has no backend
649              specific properties.
650
651       -audiodev wav,id=id[,prop[=value][,...]]
652              Creates a backend that writes audio to a WAV file.
653
654              Backend specific options are:
655
656              path=path
657                     Write recorded audio into the specified file. Default  is
658                     qemu.wav.
659
660       -soundhw card1[,card2,...] or -soundhw all
661              Enable  audio  and  selected sound hardware. Use 'help' to print
662              all available sound hardware. For example:
663
664                 qemu_system-x86_64 -soundhw sb16,adlib disk.img
665                 qemu_system-x86_64 -soundhw es1370 disk.img
666                 qemu_system-x86_64 -soundhw ac97 disk.img
667                 qemu_system-x86_64 -soundhw hda disk.img
668                 qemu_system-x86_64 -soundhw all disk.img
669                 qemu_system-x86_64 -soundhw help
670
671              Note that Linux's i810_audio OSS kernel (for AC97) module  might
672              require manually specifying clocking.
673
674                 modprobe i810_audio clocking=48000
675
676       -device driver[,prop[=value][,...]]
677              Add  device  driver.  prop=value  sets  driver properties. Valid
678              properties depend on the driver. To get help on possible drivers
679              and properties, use -device help and -device driver,help.
680
681              Some drivers are:
682
683       -device ipmi-bmc-sim,id=id[,prop[=value][,...]]
684              Add  an  IPMI BMC. This is a simulation of a hardware management
685              interface processor that normally sits on a system. It  provides
686              a  watchdog  and the ability to reset and power control the sys‐
687              tem. You need to connect this to an IPMI interface  to  make  it
688              useful
689
690              The  IPMI slave address to use for the BMC. The default is 0x20.
691              This address is the BMC's address on the I2C network of  manage‐
692              ment  controllers. If you don't know what this means, it is safe
693              to ignore it.
694
695              id=id  The BMC id for interfaces to use this device.
696
697              slave_addr=val
698                     Define slave address to use for the BMC. The  default  is
699                     0x20.
700
701              sdrfile=file
702                     file  containing  raw Sensor Data Records (SDR) data. The
703                     default is none.
704
705              fruareasize=val
706                     size of a Field Replaceable Unit (FRU) area. The  default
707                     is 1024.
708
709              frudatafile=file
710                     file  containing  raw Field Replaceable Unit (FRU) inven‐
711                     tory data.  The default is none.
712
713              guid=uuid
714                     value for the GUID for the BMC, in standard UUID  format.
715                     If  this  is  set, get "Get GUID" command to the BMC will
716                     return it.  Otherwise "Get GUID" will return an error.
717
718       -device ipmi-bmc-extern,id=id,chardev=id[,slave_addr=val]
719              Add a connection to an external IPMI BMC simulator.  Instead  of
720              locally  emulating  the BMC like the above item, instead connect
721              to an external entity that provides the IPMI services.
722
723              A connection is made to an external BMC  simulator.  If  you  do
724              this,  it  is strongly recommended that you use the "reconnect="
725              chardev option to reconnect to the simulator if  the  connection
726              is  lost.  Note  that if this is not used carefully, it can be a
727              security issue, as the interface has the ability to send resets,
728              NMIs, and power off the VM. It's best if QEMU makes a connection
729              to an external simulator running on a secure port on  localhost,
730              so neither the simulator nor QEMU is exposed to any outside net‐
731              work.
732
733              See the "lanserv/README.vm" file in  the  OpenIPMI  library  for
734              more details on the external interface.
735
736       -device isa-ipmi-kcs,bmc=id[,ioport=val][,irq=val]
737              Add a KCS IPMI interafce on the ISA bus. This also adds a corre‐
738              sponding ACPI and SMBIOS entries, if appropriate.
739
740              bmc=id The  BMC  to  connect  to,   one   of   ipmi-bmc-sim   or
741                     ipmi-bmc-extern above.
742
743              ioport=val
744                     Define  the  I/O address of the interface. The default is
745                     0xca0 for KCS.
746
747              irq=val
748                     Define the interrupt to use. The default is 5. To disable
749                     interrupts, set this to 0.
750
751       -device isa-ipmi-bt,bmc=id[,ioport=val][,irq=val]
752              Like  the KCS interface, but defines a BT interface. The default
753              port is 0xe4 and the default interrupt is 5.
754
755       -device pci-ipmi-kcs,bmc=id
756              Add a KCS IPMI interafce on the PCI bus.
757
758              bmc=id The  BMC  to  connect  to,   one   of   ipmi-bmc-sim   or
759                     ipmi-bmc-extern above.
760
761       -device pci-ipmi-bt,bmc=id
762              Like  the  KCS  interface, but defines a BT interface on the PCI
763              bus.
764
765       -name name
766              Sets the name of the guest. This name will be displayed  in  the
767              SDL  window  caption.  The  name  will  also be used for the VNC
768              server. Also optionally set the  top  visible  process  name  in
769              Linux. Naming of individual threads can also be enabled on Linux
770              to aid debugging.
771
772       -uuid uuid
773              Set system UUID.
774
775   Block device options
776       -fda file
777
778
779       -fdb file
780              Use file as floppy disk 0/1 image (see disk_005fimages).
781
782       -hda file
783
784
785       -hdb file
786
787
788       -hdc file
789
790
791       -hdd file
792              Use file as hard disk 0, 1, 2 or 3 image (see disk_005fimages).
793
794       -cdrom file
795              Use file as CD-ROM image (you cannot use -hdc and -cdrom at  the
796              same  time).  You can use the host CD-ROM by using /dev/cdrom as
797              filename.
798
799       -blockdev option[,option[,option[,...]]]
800              Define a new block driver node. Some of the options apply to all
801              block  drivers,  other  options are only accepted for a specific
802              block driver. See below  for  a  list  of  generic  options  and
803              options for the most common block drivers.
804
805              Options  that expect a reference to another node (e.g. file) can
806              be given in two ways. Either you specify the  node  name  of  an
807              already existing node (file=node-name), or you define a new node
808              inline, adding options for  the  referenced  node  after  a  dot
809              (file.filename=path,file.aio=native).
810
811              A  block  driver  node  created with -blockdev can be used for a
812              guest device by specifying its node name for the drive  property
813              in a -device argument that defines a block device.
814
815              Valid options for any block driver node:
816
817                     driver Specifies  the  block  driver to use for the given
818                            node.
819
820                     node-name
821                            This defines the name of the block driver node  by
822                            which  it  will be referenced later. The name must
823                            be unique, i.e. it must not match the  name  of  a
824                            different block driver node, or (if you use -drive
825                            as well) the ID of a drive.
826
827                            If no node name is specified, it is  automatically
828                            generated.    The   generated  node  name  is  not
829                            intended to be  predictable  and  changes  between
830                            QEMU  invocations.  For the top level, an explicit
831                            node name must be specified.
832
833                     read-only
834                            Open the node read-only. Guest write attempts will
835                            fail.
836
837                            Note   that   some   block  drivers  support  only
838                            read-only access, either generally or  in  certain
839                            configurations.  In  this  case, the default value
840                            read-only=off does not work and the option must be
841                            specified explicitly.
842
843                     auto-read-only
844                            If auto-read-only=on is set, QEMU may fall back to
845                            read-only  usage  even   when   read-only=off   is
846                            requested, or even switch between modes as needed,
847                            e.g.  depending  on  whether  the  image  file  is
848                            writable  or whether a writing user is attached to
849                            the node.
850
851                     force-share
852                            Override the image locking system of QEMU by forc‐
853                            ing  the  node to utilize weaker shared access for
854                            permissions where it would normally request exclu‐
855                            sive  access. When there is the potential for mul‐
856                            tiple  instances  to  have  the  same  file   open
857                            (whether  this  invocation of QEMU is the first or
858                            the second instance), both instances  must  permit
859                            shared  access  for the second instance to succeed
860                            at opening the file.
861
862                            Enabling force-share=on requires read-only=on.
863
864                     cache.direct
865                            The  host  page  cache   can   be   avoided   with
866                            cache.direct=on.   This will attempt to do disk IO
867                            directly to the guest's  memory.  QEMU  may  still
868                            perform an internal copy of the data.
869
870                     cache.no-flush
871                            In  case  you don't care about data integrity over
872                            host failures, you can use cache.no-flush=on. This
873                            option tells QEMU that it never needs to write any
874                            data to the disk but can instead  keep  things  in
875                            cache. If anything goes wrong, like your host los‐
876                            ing power, the disk storage  getting  disconnected
877                            accidentally,  etc.  your image will most probably
878                            be rendered unusable.
879
880                     discard=discard
881                            discard is one of "ignore" (or "off")  or  "unmap"
882                            (or "on") and controls whether discard (also known
883                            as trim or unmap) requests are ignored  or  passed
884                            to  the  filesystem.   Some  machine types may not
885                            support discard requests.
886
887                     detect-zeroes=detect-zeroes
888                            detect-zeroes  is  "off",  "on"  or  "unmap"   and
889                            enables  the  automatic  conversion  of plain zero
890                            writes by the OS to driver specific optimized zero
891                            write  commands.  You  may  even choose "unmap" if
892                            discard is set to "unmap" to allow a zero write to
893                            be converted to an unmap operation.
894
895              Driver-specific options for file
896                     This  is  the  protocol-level  block driver for accessing
897                     regular files.
898
899                     filename
900                            The path to the image file in the local filesystem
901
902                     aio    Specifies   the   AIO   backend   (threads/native,
903                            default: threads)
904
905                     locking
906                            Specifies whether the image file is protected with
907                            Linux OFD / POSIX locks. The default is to use the
908                            Linux  Open File Descriptor API if available, oth‐
909                            erwise no lock is applied.  (auto/on/off, default:
910                            auto)
911
912                     Example:
913
914                        -blockdev driver=file,node-name=disk,filename=disk.img
915
916              Driver-specific options for raw
917                     This  is the image format block driver for raw images. It
918                     is usually stacked on  top  of  a  protocol  level  block
919                     driver such as file.
920
921                     file   Reference  to  or  definition  of  the data source
922                            block driver node (e.g. a file driver node)
923
924                     Example 1:
925
926                        -blockdev driver=file,node-name=disk_file,filename=disk.img
927                        -blockdev driver=raw,node-name=disk,file=disk_file
928
929                     Example 2:
930
931                        -blockdev driver=raw,node-name=disk,file.driver=file,file.filename=disk.img
932
933              Driver-specific options for qcow2
934                     This is the image format block driver for  qcow2  images.
935                     It  is  usually  stacked on top of a protocol level block
936                     driver such as file.
937
938                     file   Reference to or  definition  of  the  data  source
939                            block driver node (e.g. a file driver node)
940
941                     backing
942                            Reference  to  or  definition  of the backing file
943                            block device (default  is  taken  from  the  image
944                            file). It is allowed to pass null here in order to
945                            disable the default backing file.
946
947                     lazy-refcounts
948                            Whether  to  enable  the  lazy  refcounts  feature
949                            (on/off; default is taken from the image file)
950
951                     cache-size
952                            The  maximum  total  size of the L2 table and ref‐
953                            count block caches in bytes (default: the  sum  of
954                            l2-cache-size and refcount-cache-size)
955
956                     l2-cache-size
957                            The  maximum  size  of the L2 table cache in bytes
958                            (default: if cache-size is not specified - 32M  on
959                            Linux  platforms,  and  8M on non-Linux platforms;
960                            otherwise,  as  large  as  possible   within   the
961                            cache-size,  while permitting the requested or the
962                            minimal refcount cache size)
963
964                     refcount-cache-size
965                            The maximum size of the refcount  block  cache  in
966                            bytes  (default:  4  times the cluster size; or if
967                            cache-size is specified, the part of it  which  is
968                            not used for the L2 cache)
969
970                     cache-clean-interval
971                            Clean  unused  entries  in  the  L2  and  refcount
972                            caches. The interval is in  seconds.  The  default
973                            value  is  600  on  supporting platforms, and 0 on
974                            other platforms. Setting it  to  0  disables  this
975                            feature.
976
977                     pass-discard-request
978                            Whether  discard  requests  to  the  qcow2  device
979                            should be forwarded to the  data  source  (on/off;
980                            default:  on  if  discard=unmap  is specified, off
981                            otherwise)
982
983                     pass-discard-snapshot
984                            Whether  discard  requests  for  the  data  source
985                            should  be  issued when a snapshot operation (e.g.
986                            deleting a snapshot) frees clusters in  the  qcow2
987                            file (on/off; default: on)
988
989                     pass-discard-other
990                            Whether  discard  requests  for  the  data  source
991                            should be issued on other occasions where a  clus‐
992                            ter gets freed (on/off; default: off)
993
994                     overlap-check
995                            Which  overlap checks to perform for writes to the
996                            image (none/constant/cached/all; default: cached).
997                            For  details or finer granularity control refer to
998                            the QAPI documentation of blockdev-add.
999
1000                     Example 1:
1001
1002                        -blockdev driver=file,node-name=my_file,filename=/tmp/disk.qcow2
1003                        -blockdev driver=qcow2,node-name=hda,file=my_file,overlap-check=none,cache-size=16777216
1004
1005                     Example 2:
1006
1007                        -blockdev driver=qcow2,node-name=disk,file.driver=http,file.filename=http://example.com/image.qcow2
1008
1009              Driver-specific options for other drivers
1010                     Please refer to the  QAPI  documentation  of  the  block‐
1011                     dev-add QMP command.
1012
1013       -drive option[,option[,option[,...]]]
1014              Define  a  new drive. This includes creating a block driver node
1015              (the backend) as well as a guest device, and is mostly a  short‐
1016              cut   for  defining  the  corresponding  -blockdev  and  -device
1017              options.
1018
1019              -drive accepts all options that are accepted by  -blockdev.   In
1020              addition, it knows the following options:
1021
1022              file=file
1023                     This  option  defines  which disk image (see disk_005fim‐
1024                     ages) to use with this drive. If  the  filename  contains
1025                     comma,  you must double it (for instance, "file=my,,file"
1026                     to use file "my,file").
1027
1028                     Special files such as  iSCSI  devices  can  be  specified
1029                     using protocol specific URLs. See the section for "Device
1030                     URL Syntax" for more information.
1031
1032              if=interface
1033                     This option defines on which type on interface the  drive
1034                     is  connected.  Available  types are: ide, scsi, sd, mtd,
1035                     floppy, pflash, virtio, none.
1036
1037              bus=bus,unit=unit
1038                     These options define where  is  connected  the  drive  by
1039                     defining the bus number and the unit id.
1040
1041              index=index
1042                     This option defines where is connected the drive by using
1043                     an index in the list of available connectors of  a  given
1044                     interface type.
1045
1046              media=media
1047                     This option defines the type of the media: disk or cdrom.
1048
1049              snapshot=snapshot
1050                     snapshot  is "on" or "off" and controls snapshot mode for
1051                     the given drive (see -snapshot).
1052
1053              cache=cache
1054                     cache is "none", "writeback", "unsafe",  "directsync"  or
1055                     "writethrough" and controls how the host cache is used to
1056                     access block data. This  is  a  shortcut  that  sets  the
1057                     cache.direct  and  cache.no-flush  options (as in -block‐
1058                     dev), and additionally cache.writeback, which provides  a
1059                     default for the write-cache option of block guest devices
1060                     (as in -device). The modes correspond  to  the  following
1061                     settings:
1062
1063
1064
1065                  ┌─────────────┬─────────────────┬──────────────┬────────────────┐
1066                  │             │ cache.writeback │ cache.direct │ cache.no-flush │
1067                  ├─────────────┼─────────────────┼──────────────┼────────────────┤
1068                  │writeback    │ on              │ off          │ off            │
1069                  ├─────────────┼─────────────────┼──────────────┼────────────────┤
1070                  │none         │ on              │ on           │ off            │
1071                  ├─────────────┼─────────────────┼──────────────┼────────────────┤
1072                  │writethrough │ off             │ off          │ off            │
1073                  ├─────────────┼─────────────────┼──────────────┼────────────────┤
1074                  │directsync   │ off             │ on           │ off            │
1075                  ├─────────────┼─────────────────┼──────────────┼────────────────┤
1076                  │unsafe       │ on              │ off          │ on             │
1077                  └─────────────┴─────────────────┴──────────────┴────────────────┘
1078
1079                     The default mode is cache=writeback.
1080
1081              aio=aio
1082                     aio is "threads", or "native" and selects between pthread
1083                     based disk I/O and native Linux AIO.
1084
1085              format=format
1086                     Specify which  disk  format  will  be  used  rather  than
1087                     detecting  the  format. Can be used to specify format=raw
1088                     to avoid interpreting an untrusted format header.
1089
1090              werror=action,rerror=action
1091                     Specify which action to take on write  and  read  errors.
1092                     Valid  actions are: "ignore" (ignore the error and try to
1093                     continue), "stop"  (pause  QEMU),  "report"  (report  the
1094                     error  to  the  guest),  "enospc" (pause QEMU only if the
1095                     host disk is full; report the error to the  guest  other‐
1096                     wise).   The   default   setting   is  werror=enospc  and
1097                     rerror=report.
1098
1099              copy-on-read=copy-on-read
1100                     copy-on-read is "on" or "off" and enables whether to copy
1101                     read backing file sectors into the image file.
1102
1103              bps=b,bps_rd=r,bps_wr=w
1104                     Specify  bandwidth throttling limits in bytes per second,
1105                     either for all request types or for reads or writes only.
1106                     Small  values  can  lead  to timeouts or hangs inside the
1107                     guest. A safe minimum for disks is 2 MB/s.
1108
1109              bps_max=bm,bps_rd_max=rm,bps_wr_max=wm
1110                     Specify bursts  in  bytes  per  second,  either  for  all
1111                     request  types  or for reads or writes only. Bursts allow
1112                     the guest I/O to spike above the limit temporarily.
1113
1114              iops=i,iops_rd=r,iops_wr=w
1115                     Specify request  rate  limits  in  requests  per  second,
1116                     either for all request types or for reads or writes only.
1117
1118              iops_max=bm,iops_rd_max=rm,iops_wr_max=wm
1119                     Specify  bursts  in  requests  per second, either for all
1120                     request types or for reads or writes only.  Bursts  allow
1121                     the guest I/O to spike above the limit temporarily.
1122
1123              iops_size=is
1124                     Let  every  is  bytes of a request count as a new request
1125                     for iops throttling purposes. Use this option to  prevent
1126                     guests  from  circumventing  iops limits by sending fewer
1127                     but larger requests.
1128
1129              group=g
1130                     Join a throttling quota group  with  given  name  g.  All
1131                     drives  that  are members of the same group are accounted
1132                     for together. Use this option to prevent guests from cir‐
1133                     cumventing  throttling  limits  by using many small disks
1134                     instead of a single larger disk.
1135
1136              By default, the cache.writeback=on mode is used. It will  report
1137              data  writes  as completed as soon as the data is present in the
1138              host page cache. This is safe as long as  your  guest  OS  makes
1139              sure  to correctly flush disk caches where needed. If your guest
1140              OS does not handle volatile disk write caches correctly and your
1141              host  crashes or loses power, then the guest may experience data
1142              corruption.
1143
1144              For such guests, you should consider using  cache.writeback=off.
1145              This  means  that  the  host page cache will be used to read and
1146              write data, but write notification will be  sent  to  the  guest
1147              only  after  QEMU has made sure to flush each write to the disk.
1148              Be aware that this has a major impact on performance.
1149
1150              When using the -snapshot option, unsafe caching is always used.
1151
1152              Copy-on-read avoids accessing  the  same  backing  file  sectors
1153              repeatedly  and  is  useful when the backing file is over a slow
1154              network. By default copy-on-read is off.
1155
1156              Instead of -cdrom you can use:
1157
1158                 qemu-system-x86_64 -drive file=file,index=2,media=cdrom
1159
1160              Instead of -hda, -hdb, -hdc, -hdd, you can use:
1161
1162                 qemu-system-x86_64 -drive file=file,index=0,media=disk
1163                 qemu-system-x86_64 -drive file=file,index=1,media=disk
1164                 qemu-system-x86_64 -drive file=file,index=2,media=disk
1165                 qemu-system-x86_64 -drive file=file,index=3,media=disk
1166
1167              You can open an image using pre-opened file descriptors from  an
1168              fd set:
1169
1170                 qemu-system-x86_64  -add-fd fd=3,set=2,opaque="rdwr:/path/to/file"  -add-fd fd=4,set=2,opaque="rdonly:/path/to/file"  -drive file=/dev/fdset/2,index=0,media=disk
1171
1172              You can connect a CDROM to the slave of ide0:
1173
1174                 qemu_system-x86_64 -drive file=file,if=ide,index=1,media=cdrom
1175
1176              If  you  don't specify the "file=" argument, you define an empty
1177              drive:
1178
1179                 qemu_system-x86_64 -drive if=ide,index=1,media=cdrom
1180
1181              Instead of -fda, -fdb, you can use:
1182
1183                 qemu_system-x86_64 -drive file=file,index=0,if=floppy
1184                 qemu_system-x86_64 -drive file=file,index=1,if=floppy
1185
1186              By default, interface is "ide" and index is automatically incre‐
1187              mented:
1188
1189                 qemu_system-x86_64 -drive file=a -drive file=b"
1190
1191              is interpreted like:
1192
1193                 qemu_system-x86_64 -hda a -hdb b
1194
1195       -mtdblock file
1196              Use file as on-board Flash memory image.
1197
1198       -sd file
1199              Use file as SecureDigital card image.
1200
1201       -pflash file
1202              Use file as a parallel flash image.
1203
1204       -snapshot
1205              Write  to  temporary  files instead of disk image files. In this
1206              case, the raw disk image you use is not written  back.  You  can
1207              however force the write back by pressing C-a s (see disk_005fim‐
1208              ages).
1209
1210       -fsdev   local,id=id,path=path,security_model=security_model   [,write‐
1211       out=writeout][,readonly][,fmode=fmode][,dmode=dmode]           [,throt‐
1212       tling.option=value[,throttling.option=value[,...]]]
1213
1214
1215       -fsdev proxy,id=id,socket=socket[,writeout=writeout][,readonly]
1216
1217
1218       -fsdev proxy,id=id,sock_fd=sock_fd[,writeout=writeout][,readonly]
1219
1220
1221       -fsdev synth,id=id[,readonly]
1222              Define a new file system device. Valid options are:
1223
1224              local  Accesses to the filesystem are done by QEMU.
1225
1226              proxy  Accesses    to    the    filesystem    are    done     by
1227                     virtfs-proxy-helper(1).
1228
1229              synth  Synthetic filesystem, only used by QTests.
1230
1231              id=id  Specifies identifier for this device.
1232
1233              path=path
1234                     Specifies  the  export  path  for the file system device.
1235                     Files under this path will be available to the 9p  client
1236                     on the guest.
1237
1238              security_model=security_model
1239                     Specifies  the  security model to be used for this export
1240                     path.   Supported  security  models  are   "passthrough",
1241                     "mapped-xattr",     "mapped-file"    and    "none".    In
1242                     "passthrough" security model, files are stored using  the
1243                     same  credentials  as they are created on the guest. This
1244                     requires QEMU to run as root. In "mapped-xattr"  security
1245                     model,  some  of  the file attributes like uid, gid, mode
1246                     bits and link target are stored as file  attributes.  For
1247                     "mapped-file"  these  attributes are stored in the hidden
1248                     .virtfs_metadata directory. Directories exported by  this
1249                     security  model  cannot  interact  with other unix tools.
1250                     "none" security model is same as passthrough  except  the
1251                     sever  won't  report  failures  if  it  fails to set file
1252                     attributes like ownership. Security  model  is  mandatory
1253                     only  for  local  fsdriver.  Other fsdrivers (like proxy)
1254                     don't take security model as a parameter.
1255
1256              writeout=writeout
1257                     This is an optional argument. The only supported value is
1258                     "immediate". This means that host page cache will be used
1259                     to read and write data but  write  notification  will  be
1260                     sent to the guest only when the data has been reported as
1261                     written by the storage subsystem.
1262
1263              readonly
1264                     Enables exporting  9p  share  as  a  readonly  mount  for
1265                     guests. By default read-write access is given.
1266
1267              socket=socket
1268                     Enables proxy filesystem driver to use passed socket file
1269                     for communicating with virtfs-proxy-helper(1).
1270
1271              sock_fd=sock_fd
1272                     Enables proxy filesystem  driver  to  use  passed  socket
1273                     descriptor for communicating with virtfs-proxy-helper(1).
1274                     Usually a helper like libvirt will create socketpair  and
1275                     pass one of the fds as sock_fd.
1276
1277              fmode=fmode
1278                     Specifies the default mode for newly created files on the
1279                     host.  Works only with security models "mapped-xattr" and
1280                     "mapped-file".
1281
1282              dmode=dmode
1283                     Specifies  the default mode for newly created directories
1284                     on  the   host.   Works   only   with   security   models
1285                     "mapped-xattr" and "mapped-file".
1286
1287              throttling.bps-total=b,throttling.bps-read=r,throt‐
1288              tling.bps-write=w
1289                     Specify bandwidth throttling limits in bytes per  second,
1290                     either for all request types or for reads or writes only.
1291
1292              throttling.bps-total-max=bm,bps-read-max=rm,bps-write-max=wm
1293                     Specify  bursts  in  bytes  per  second,  either  for all
1294                     request types or for reads or writes only.  Bursts  allow
1295                     the guest I/O to spike above the limit temporarily.
1296
1297              throttling.iops-total=i,throttling.iops-read=r,           throt‐
1298              tling.iops-write=w
1299                     Specify request  rate  limits  in  requests  per  second,
1300                     either for all request types or for reads or writes only.
1301
1302              throttling.iops-total-max=im,throttling.iops-read-max=irm,
1303              throttling.iops-write-max=iwm
1304                     Specify bursts in requests per  second,  either  for  all
1305                     request  types  or for reads or writes only. Bursts allow
1306                     the guest I/O to spike above the limit temporarily.
1307
1308              throttling.iops-size=is
1309                     Let every is bytes of a request count as  a  new  request
1310                     for iops throttling purposes.
1311
1312              -fsdev option is used along with -device driver "virtio-9p-...".
1313
1314       -device virtio-9p-type,fsdev=id,mount_tag=mount_tag
1315              Options for virtio-9p-... driver are:
1316
1317              type   Specifies  the  variant  to be used. Supported values are
1318                     "pci", "ccw" or "device", depending on the machine type.
1319
1320              fsdev=id
1321                     Specifies  the  id  value  specified  along  with  -fsdev
1322                     option.
1323
1324              mount_tag=mount_tag
1325                     Specifies  the  tag name to be used by the guest to mount
1326                     this export point.
1327
1328       -virtfs    local,path=path,mount_tag=mount_tag    ,security_model=secu‐
1329       rity_model[,writeout=writeout][,readonly]
1330       [,fmode=fmode][,dmode=dmode][,multidevs=multidevs]
1331
1332
1333       -virtfs    proxy,socket=socket,mount_tag=mount_tag    [,writeout=write‐
1334       out][,readonly]
1335
1336
1337       -virtfs   proxy,sock_fd=sock_fd,mount_tag=mount_tag   [,writeout=write‐
1338       out][,readonly]
1339
1340
1341       -virtfs synth,mount_tag=mount_tag
1342              Define a new virtual filesystem device  and  expose  it  to  the
1343              guest  using a virtio-9p-device (a.k.a. 9pfs), which essentially
1344              means that a certain directory on host is made directly accessi‐
1345              ble  by guest as a pass-through file system by using the 9P net‐
1346              work protocol for communication  between  host  and  guests,  if
1347              desired  even  accessible,  shared  by  several guests simultan‐
1348              iously.
1349
1350              Note that -virtfs is actually just a  convenience  shortcut  for
1351              its generalized form -fsdev -device virtio-9p-pci.
1352
1353              The general form of pass-through file system options are:
1354
1355              local  Accesses to the filesystem are done by QEMU.
1356
1357              proxy  Accesses     to    the    filesystem    are    done    by
1358                     virtfs-proxy-helper(1).
1359
1360              synth  Synthetic filesystem, only used by QTests.
1361
1362              id=id  Specifies identifier for the filesystem device
1363
1364              path=path
1365                     Specifies the export path for  the  file  system  device.
1366                     Files  under this path will be available to the 9p client
1367                     on the guest.
1368
1369              security_model=security_model
1370                     Specifies the security model to be used for  this  export
1371                     path.    Supported  security  models  are  "passthrough",
1372                     "mapped-xattr",    "mapped-file"    and    "none".     In
1373                     "passthrough"  security model, files are stored using the
1374                     same credentials as they are created on the  guest.  This
1375                     requires  QEMU to run as root. In "mapped-xattr" security
1376                     model, some of the file attributes like  uid,  gid,  mode
1377                     bits  and  link target are stored as file attributes. For
1378                     "mapped-file" these attributes are stored in  the  hidden
1379                     .virtfs_metadata  directory. Directories exported by this
1380                     security model cannot interact  with  other  unix  tools.
1381                     "none"  security  model is same as passthrough except the
1382                     sever won't report failures  if  it  fails  to  set  file
1383                     attributes  like  ownership.  Security model is mandatory
1384                     only for local fsdriver.  Other  fsdrivers  (like  proxy)
1385                     don't take security model as a parameter.
1386
1387              writeout=writeout
1388                     This is an optional argument. The only supported value is
1389                     "immediate". This means that host page cache will be used
1390                     to  read  and  write  data but write notification will be
1391                     sent to the guest only when the data has been reported as
1392                     written by the storage subsystem.
1393
1394              readonly
1395                     Enables  exporting  9p  share  as  a  readonly  mount for
1396                     guests. By default read-write access is given.
1397
1398              socket=socket
1399                     Enables proxy filesystem driver to use passed socket file
1400                     for  communicating with virtfs-proxy-helper(1). Usually a
1401                     helper like libvirt will create socketpair and  pass  one
1402                     of the fds as sock_fd.
1403
1404              sock_fd
1405                     Enables  proxy  filesystem driver to use passed 'sock_fd'
1406                     as   the   socket   descriptor   for   interfacing   with
1407                     virtfs-proxy-helper(1).
1408
1409              fmode=fmode
1410                     Specifies the default mode for newly created files on the
1411                     host.  Works only with security models "mapped-xattr" and
1412                     "mapped-file".
1413
1414              dmode=dmode
1415                     Specifies  the default mode for newly created directories
1416                     on  the   host.   Works   only   with   security   models
1417                     "mapped-xattr" and "mapped-file".
1418
1419              mount_tag=mount_tag
1420                     Specifies  the  tag name to be used by the guest to mount
1421                     this export point.
1422
1423              multidevs=multidevs
1424                     Specifies how to deal with multiple devices being  shared
1425                     with   a  9p  export.  Supported  behaviours  are  either
1426                     "remap", "forbid" or "warn". The latter  is  the  default
1427                     behaviour  on  which virtfs 9p expects only one device to
1428                     be shared with the same export,  and  if  more  than  one
1429                     device is shared and accessed via the same 9p export then
1430                     only a warning message is logged (once) by qemu  on  host
1431                     side.  In  order to avoid file ID collisions on guest you
1432                     should either create a separate virtfs  export  for  each
1433                     device  to be shared with guests (recommended way) or you
1434                     might use "remap" instead which allows you to share  mul‐
1435                     tiple  devices  with  only  one  export instead, which is
1436                     achieved by remapping the  original  inode  numbers  from
1437                     host  to  guest  in  a way that would prevent such colli‐
1438                     sions. Remapping inodes in such  use  cases  is  required
1439                     because  the  original  device  IDs  from  host are never
1440                     passed and exposed on guest.  Instead  all  files  of  an
1441                     export shared with virtfs always share the same device id
1442                     on guest. So two files with identical inode  numbers  but
1443                     from  actually  different devices on host would otherwise
1444                     cause a file ID  collision  and  hence  potential  misbe‐
1445                     haviours  on  guest.  "forbid"  on the other hand assumes
1446                     like "warn" that only one device is shared  by  the  same
1447                     export,  however  it  will not only log a warning message
1448                     but also deny access to additional devices on guest. Note
1449                     though  that "forbid" does currently not block all possi‐
1450                     ble file access operations (e.g.  readdir()  would  still
1451                     return entries from other devices).
1452
1453       -iscsi Configure iSCSI session parameters.
1454
1455   USB options
1456       -usb   Enable  USB emulation on machine types with an on-board USB host
1457              controller (if not enabled by default). Note that  on-board  USB
1458              host  controllers  may not support USB 3.0. In this case -device
1459              qemu-xhci can be used instead on machines with PCI.
1460
1461       -usbdevice devname
1462              Add the USB device devname. Note that this option is deprecated,
1463              please use -device usb-... instead. See usb_005fdevices.
1464
1465              mouse  Virtual  Mouse.  This will override the PS/2 mouse emula‐
1466                     tion when activated.
1467
1468              tablet Pointer device that uses  absolute  coordinates  (like  a
1469                     touchscreen). This means QEMU is able to report the mouse
1470                     position without having to grab the mouse. Also overrides
1471                     the PS/2 mouse emulation when activated.
1472
1473              braille
1474                     Braille  device.  This  will  use  BrlAPI  to display the
1475                     braille output on a real or fake device.
1476
1477   Display options
1478       -display type
1479              Select type of display to use. This option is a replacement  for
1480              the  old  style  -sdl/-curses/...  options. Use -display help to
1481              list the available display types. Valid values for type are
1482
1483              sdl    Display video output  via  SDL  (usually  in  a  separate
1484                     graphics window; see the SDL documentation for other pos‐
1485                     sibilities).
1486
1487              curses Display video output via curses. For graphics device mod‐
1488                     els which support a text mode, QEMU can display this out‐
1489                     put using a curses/ncurses  interface.  Nothing  is  dis‐
1490                     played  when  the graphics device is in graphical mode or
1491                     if the graphics device does not support a text mode. Gen‐
1492                     erally  only the VGA device models support text mode. The
1493                     font charset used by the guest can be specified with  the
1494                     charset  option,  for example charset=CP850 for IBM CP850
1495                     encoding. The default is CP437.
1496
1497              none   Do not display video output. The guest will still see  an
1498                     emulated  graphics  card, but its output will not be dis‐
1499                     played to the QEMU user. This  option  differs  from  the
1500                     -nographic  option  in  that it only affects what is done
1501                     with video output; -nographic also changes  the  destina‐
1502                     tion of the serial and parallel port data.
1503
1504              gtk    Display video output in a GTK window. This interface pro‐
1505                     vides drop-down menus and other UI elements to  configure
1506                     and control the VM during runtime.
1507
1508              vnc    Start a VNC server on display <arg>
1509
1510              egl-headless
1511                     Offload  all OpenGL operations to a local DRI device. For
1512                     any graphical display, this display needs  to  be  paired
1513                     with either VNC or SPICE displays.
1514
1515              spice-app
1516                     Start QEMU as a Spice server and launch the default Spice
1517                     client application. The Spice server  will  redirect  the
1518                     serial consoles and QEMU monitors. (Since 4.0)
1519
1520       -nographic
1521              Normally,  if QEMU is compiled with graphical window support, it
1522              displays output such as guest graphics, guest console,  and  the
1523              QEMU monitor in a window. With this option, you can totally dis‐
1524              able graphical output so that QEMU  is  a  simple  command  line
1525              application.  The emulated serial port is redirected on the con‐
1526              sole and muxed with the  monitor  (unless  redirected  elsewhere
1527              explicitly).  Therefore, you can still use QEMU to debug a Linux
1528              kernel with a serial console.  Use C-a h for help  on  switching
1529              between the console and monitor.
1530
1531       -curses
1532              Normally,  if QEMU is compiled with graphical window support, it
1533              displays output such as guest graphics, guest console,  and  the
1534              QEMU monitor in a window. With this option, QEMU can display the
1535              VGA output when in text mode using a  curses/ncurses  interface.
1536              Nothing is displayed in graphical mode.
1537
1538       -alt-grab
1539              Use  Ctrl-Alt-Shift  to  grab  mouse (instead of Ctrl-Alt). Note
1540              that this also affects the special keys (for  fullscreen,  moni‐
1541              tor-mode switching, etc).
1542
1543       -ctrl-grab
1544              Use  Right-Ctrl  to  grab mouse (instead of Ctrl-Alt). Note that
1545              this also affects the special keys (for fullscreen, monitor-mode
1546              switching, etc).
1547
1548       -no-quit
1549              Disable SDL window close capability.
1550
1551       -sdl   Enable SDL.
1552
1553       -spice option[,option[,...]]
1554              Enable the spice remote desktop protocol. Valid options are
1555
1556              port=<nr>
1557                     Set  the  TCP  port  spice  is listening on for plaintext
1558                     channels.
1559
1560              addr=<addr>
1561                     Set the IP address spice is listening on. Default is  any
1562                     address.
1563
1564              ipv4; ipv6; unix
1565                     Force using the specified IP version.
1566
1567              password=<secret>
1568                     Set the password you need to authenticate.
1569
1570              sasl   Require that the client use SASL to authenticate with the
1571                     spice.  The exact choice of authentication method used is
1572                     controlled  from  the  system / user's SASL configuration
1573                     file for the 'qemu' service. This is typically  found  in
1574                     /etc/sasl2/qemu.conf.  If running QEMU as an unprivileged
1575                     user, an environment variable SASL_CONF_PATH can be  used
1576                     to  make  it  search  alternate locations for the service
1577                     config. While some SASL auth  methods  can  also  provide
1578                     data  encryption (eg GSSAPI), it is recommended that SASL
1579                     always be combined with the 'tls' and 'x509' settings  to
1580                     enable use of SSL and server certificates. This ensures a
1581                     data encryption preventing compromise  of  authentication
1582                     credentials.
1583
1584              disable-ticketing
1585                     Allow client connects without authentication.
1586
1587              disable-copy-paste
1588                     Disable copy paste between the client and the guest.
1589
1590              disable-agent-file-xfer
1591                     Disable  spice-vdagent based file-xfer between the client
1592                     and the guest.
1593
1594              tls-port=<nr>
1595                     Set the TCP port spice  is  listening  on  for  encrypted
1596                     channels.
1597
1598              x509-dir=<dir>
1599                     Set  the  x509  file directory. Expects same filenames as
1600                     -vnc $display,x509=$dir
1601
1602              x509-key-file=<file>;                  x509-key-password=<file>;
1603              x509-cert-file=<file>;                  x509-cacert-file=<file>;
1604              x509-dh-key-file=<file>
1605                     The x509 file names can also be configured individually.
1606
1607              tls-ciphers=<list>
1608                     Specify which ciphers to use.
1609
1610              tls-channel=[main|display|cursor|inputs|record|playback]; plain‐
1611              text-channel=[main|display|cursor|inputs|record|playback]
1612                     Force  specific  channel  to  be used with or without TLS
1613                     encryption. The options can be specified  multiple  times
1614                     to   configure   multiple   channels.  The  special  name
1615                     "default" can be used to set the default mode. For  chan‐
1616                     nels  which  are  not explicitly forced into one mode the
1617                     spice client is  allowed  to  pick  tls/plaintext  as  he
1618                     pleases.
1619
1620              image-compression=[auto_glz|auto_lz|quic|glz|lz|off]
1621                     Configure   image   compression  (lossless).  Default  is
1622                     auto_glz.
1623
1624              jpeg-wan-compression=[auto|never|always];  zlib-glz-wan-compres‐
1625              sion=[auto|never|always]
1626                     Configure  wan  image compression (lossy for slow links).
1627                     Default is auto.
1628
1629              streaming-video=[off|all|filter]
1630                     Configure video stream detection. Default is off.
1631
1632              agent-mouse=[on|off]
1633                     Enable/disable passing mouse events via vdagent.  Default
1634                     is on.
1635
1636              playback-compression=[on|off]
1637                     Enable/disable   audio  stream  compression  (using  celt
1638                     0.5.1).  Default is on.
1639
1640              seamless-migration=[on|off]
1641                     Enable/disable spice seamless migration. Default is off.
1642
1643              gl=[on|off]
1644                     Enable/disable OpenGL context. Default is off.
1645
1646              rendernode=<file>
1647                     DRM render node for OpenGL rendering. If  not  specified,
1648                     it will pick the first available. (Since 2.9)
1649
1650       -portrait
1651              Rotate graphical output 90 deg left (only PXA LCD).
1652
1653       -rotate deg
1654              Rotate graphical output some deg left (only PXA LCD).
1655
1656       -vga type
1657              Select type of VGA card to emulate. Valid values for type are
1658
1659              cirrus Cirrus  Logic  GD5446  Video  card.  All Windows versions
1660                     starting from Windows 95 should recognize  and  use  this
1661                     graphic  card. For optimal performances, use 16 bit color
1662                     depth in the guest and the host OS. (This  card  was  the
1663                     default before QEMU 2.2)
1664
1665              std    Standard  VGA  card  with  Bochs  VBE extensions. If your
1666                     guest OS supports the VESA 2.0 VBE extensions (e.g.  Win‐
1667                     dows XP) and if you want to use high resolution modes (>=
1668                     1280x1024x16) then you should use this option. (This card
1669                     is the default since QEMU 2.2)
1670
1671              vmware VMWare  SVGA-II  compatible  adapter.  Use it if you have
1672                     sufficiently recent XFree86/XOrg server or Windows  guest
1673                     with a driver for this card.
1674
1675              qxl    QXL  paravirtual  graphic  card.  It  is  VGA  compatible
1676                     (including VESA 2.0 VBE support).  Works  best  with  qxl
1677                     guest  drivers  installed though. Recommended choice when
1678                     using the spice protocol.
1679
1680              tcx    (sun4m only) Sun TCX framebuffer.  This  is  the  default
1681                     framebuffer  for sun4m machines and offers both 8-bit and
1682                     24-bit colour depths at a fixed resolution of 1024x768.
1683
1684              cg3    (sun4m only) Sun cgthree framebuffer. This  is  a  simple
1685                     8-bit  framebuffer  for  sun4m machines available in both
1686                     1024x768 (OpenBIOS) and 1152x900 (OBP) resolutions  aimed
1687                     at people wishing to run older Solaris versions.
1688
1689              virtio Virtio VGA card.
1690
1691              none   Disable VGA card.
1692
1693       -full-screen
1694              Start in full screen.
1695
1696       -g widthxheight[xdepth]
1697              Set  the  initial  graphical  resolution  and  depth (PPC, SPARC
1698              only).
1699
1700              For PPC the default is 800x600x32.
1701
1702              For  SPARC  with  the  TCX  graphics  device,  the  default   is
1703              1024x768x8  with  the  option  of  1024x768x24. For cgthree, the
1704              default is 1024x768x8 with the option of 1152x900x8  for  people
1705              who wish to use OBP.
1706
1707       -vnc display[,option[,option[,...]]]
1708              Normally,  if QEMU is compiled with graphical window support, it
1709              displays output such as guest graphics, guest console,  and  the
1710              QEMU  monitor  in  a window. With this option, you can have QEMU
1711              listen on VNC display display and redirect the VGA display  over
1712              the  VNC  session.  It  is  very useful to enable the usb tablet
1713              device when using this option (option -device usb-tablet).  When
1714              using  the VNC display, you must use the -k parameter to set the
1715              keyboard layout if you are not using en-us. Valid syntax for the
1716              display is
1717
1718              to=L   With  this  option, QEMU will try next available VNC dis‐
1719                     plays, until the number  L,  if  the  origianlly  defined
1720                     "-vnc  display"  is not available, e.g. port 5900+display
1721                     is already used by another application. By default, to=0.
1722
1723              host:d TCP connections will only be allowed from host on display
1724                     d. By convention the TCP port is 5900+d. Optionally, host
1725                     can be omitted in which case the server will accept  con‐
1726                     nections from any host.
1727
1728              unix:path
1729                     Connections  will  be  allowed  over  UNIX domain sockets
1730                     where path is the location of a unix socket to listen for
1731                     connections on.
1732
1733              none   VNC  is  initialized  but not started. The monitor change
1734                     command can be used to later start the VNC server.
1735
1736              Following the display value there may  be  one  or  more  option
1737              flags separated by commas. Valid options are
1738
1739              reverse
1740                     Connect to a listening VNC client via a "reverse" connec‐
1741                     tion.  The  client  is  specified  by  the  display.  For
1742                     reverse  network  connections (host:d,``reverse``), the d
1743                     argument is a TCP port number, not a display number.
1744
1745              websocket
1746                     Opens an additional TCP listening port dedicated  to  VNC
1747                     Websocket  connections.  If  a  bare  websocket option is
1748                     given, the Websocket port is 5700+display. An alternative
1749                     port can be specified with the syntax websocket=port.
1750
1751                     If  host  is  specified  connections will only be allowed
1752                     from this host. It is possible to control  the  websocket
1753                     listen  address  independently,  using  the  syntax  web‐
1754                     socket=host:port.
1755
1756                     If no TLS credentials are provided, the websocket connec‐
1757                     tion  runs  in  unencrypted  mode. If TLS credentials are
1758                     provided, the  websocket  connection  requires  encrypted
1759                     client connections.
1760
1761              password
1762                     Require  that  password  based authentication is used for
1763                     client connections.
1764
1765                     The password must be set separately using  the  set_pass‐
1766                     word  command  in  the  pcsys_005fmonitor.  The syntax to
1767                     change your password is: set_password  <protocol>  <pass‐
1768                     word> where <protocol> could be either "vnc" or "spice".
1769
1770                     If  you  would like to change <protocol> password expira‐
1771                     tion, you should use expire_password <protocol>  <expira‐
1772                     tion-time> where expiration time could be one of the fol‐
1773                     lowing options: now, never,  +seconds  or  UNIX  time  of
1774                     expiration,  e.g.  +60 to make password expire in 60 sec‐
1775                     onds, or 1335196800 to make password expire on  "Mon  Apr
1776                     23 12:00:00 EDT 2012" (UNIX time for this date and time).
1777
1778                     You  can also use keywords "now" or "never" for the expi‐
1779                     ration time to allow <protocol> password to expire  imme‐
1780                     diately or never expire.
1781
1782              tls-creds=ID
1783                     Provides  the  ID  of  a set of TLS credentials to use to
1784                     secure the VNC server. They will apply to both the normal
1785                     VNC  server socket and the websocket socket (if enabled).
1786                     Setting TLS credentials will cause the VNC server  socket
1787                     to  enable  the  VeNCrypt auth mechanism. The credentials
1788                     should have been previously  created  using  the  -object
1789                     tls-creds argument.
1790
1791              tls-authz=ID
1792                     Provides  the  ID  of  the  QAuthZ  authorization  object
1793                     against which the client's x509 distinguished  name  will
1794                     validated.  This  object is only resolved at time of use,
1795                     so can be deleted and recreated on the fly while the  VNC
1796                     server  is active. If missing, it will default to denying
1797                     access.
1798
1799              sasl   Require that the client use SASL to authenticate with the
1800                     VNC  server.  The  exact  choice of authentication method
1801                     used is controlled from the system / user's SASL configu‐
1802                     ration  file  for  the  'qemu' service. This is typically
1803                     found in /etc/sasl2/qemu.conf.  If  running  QEMU  as  an
1804                     unprivileged user, an environment variable SASL_CONF_PATH
1805                     can be used to make it search alternate locations for the
1806                     service  config.  While  some  SASL auth methods can also
1807                     provide data encryption (eg GSSAPI),  it  is  recommended
1808                     that  SASL  always  be combined with the 'tls' and 'x509'
1809                     settings to enable use of SSL  and  server  certificates.
1810                     This  ensures  a data encryption preventing compromise of
1811                     authentication credentials. See the vnc_005fsecurity sec‐
1812                     tion for details on using SASL authentication.
1813
1814              sasl-authz=ID
1815                     Provides  the  ID  of  the  QAuthZ  authorization  object
1816                     against which the client's SASL username will  validated.
1817                     This  object  is  only resolved at time of use, so can be
1818                     deleted and recreated on the fly while the VNC server  is
1819                     active. If missing, it will default to denying access.
1820
1821              acl    Legacy  method  for  enabling  authorization  of  clients
1822                     against the x509 distinguished name and SASL username. It
1823                     results  in  the  creation of two authz-list objects with
1824                     IDs of vnc.username  and  vnc.x509dname.  The  rules  for
1825                     these  objects  must  be configured with the HMP ACL com‐
1826                     mands.
1827
1828                     This option is deprecated and should no longer  be  used.
1829                     The  new  sasl-authz and tls-authz options are a replace‐
1830                     ment.
1831
1832              lossy  Enable lossy compression methods (gradient,  JPEG,  ...).
1833                     If  this  option  is  set,  VNC  client may receive lossy
1834                     framebuffer updates depending on its  encoding  settings.
1835                     Enabling  this  option can save a lot of bandwidth at the
1836                     expense of quality.
1837
1838              non-adaptive
1839                     Disable  adaptive  encodings.  Adaptive   encodings   are
1840                     enabled  by  default.  An  adaptive  encoding will try to
1841                     detect  frequently  updated  screen  regions,  and   send
1842                     updates  in  these  regions  using a lossy encoding (like
1843                     JPEG). This can be really helpful to save bandwidth  when
1844                     playing videos. Disabling adaptive encodings restores the
1845                     original static behavior of encodings like Tight.
1846
1847              share=[allow-exclusive|force-shared|ignore]
1848                     Set  display  sharing  policy.  'allow-exclusive'  allows
1849                     clients  to ask for exclusive access. As suggested by the
1850                     rfb spec this is implemented by  dropping  other  connec‐
1851                     tions.  Connecting  multiple clients in parallel requires
1852                     all clients  asking  for  a  shared  session  (vncviewer:
1853                     -shared  switch).  This  is  the default.  'force-shared'
1854                     disables exclusive client access. Useful for shared desk‐
1855                     top  sessions,  where  you  don't want someone forgetting
1856                     specify -shared disconnect everybody else. 'ignore'  com‐
1857                     pletely ignores the shared flag and allows everybody con‐
1858                     nect unconditionally. Doesn't conform to the rfb spec but
1859                     is traditional QEMU behavior.
1860
1861              key-delay-ms
1862                     Set  keyboard  delay,  for key down and key up events, in
1863                     milliseconds. Default is 10. Keyboards are  low-bandwidth
1864                     devices,  so  this slowdown can help the device and guest
1865                     to keep up and not lose events in case events are  arriv‐
1866                     ing  in  bulk.   Possible causes for the latter are flaky
1867                     network connections, or scripts for automated testing.
1868
1869              audiodev=audiodev
1870                     Use the specified audiodev when the VNC  client  requests
1871                     audio transmission. When not using an -audiodev argument,
1872                     this option must be omitted, otherwise is must be present
1873                     and specify a valid audiodev.
1874
1875   i386 target only
1876       -win2k-hack
1877              Use  it  when  installing Windows 2000 to avoid a disk full bug.
1878              After Windows 2000 is installed, you no longer need this  option
1879              (this option slows down the IDE transfers).
1880
1881       -no-fd-bootchk
1882              Disable boot signature checking for floppy disks in BIOS. May be
1883              needed to boot from old floppy disks.
1884
1885       -no-acpi
1886              Disable ACPI (Advanced Configuration and Power  Interface)  sup‐
1887              port.  Use it if your guest OS complains about ACPI problems (PC
1888              target machine only).
1889
1890       -no-hpet
1891              Disable HPET support.
1892
1893       -acpitable                      [sig=str][,rev=n][,oem_id=str][,oem_ta‐
1894       ble_id=str][,oem_rev=n]                [,asl_compiler_id=str][,asl_com‐
1895       piler_rev=n][,data=file1[:file2]...]
1896              Add ACPI table with specified header  fields  and  context  from
1897              specified files. For file=, take whole ACPI table from the spec‐
1898              ified files, including all ACPI headers (possible overridden  by
1899              other  options).  For  data=,  only data portion of the table is
1900              used, all header information is specified in the  command  line.
1901              If  a SLIC table is supplied to QEMU, then the SLIC's oem_id and
1902              oem_table_id fields will override the same in the RSDT  and  the
1903              FADT  (a.k.a.   FACP),  in  order  to  ensure  the field matches
1904              required by the Microsoft SLIC spec and the ACPI spec.
1905
1906       -smbios file=binary
1907              Load SMBIOS entry from binary file.
1908
1909       -smbios                                       type=0[,vendor=str][,ver‐
1910       sion=str][,date=str][,release=%d.%d][,uefi=on|off]
1911              Specify SMBIOS type 0 fields
1912
1913       -smbios                   type=1[,manufacturer=str][,product=str][,ver‐
1914       sion=str][,serial=str][,uuid=uuid][,sku=str][,family=str]
1915              Specify SMBIOS type 1 fields
1916
1917       -smbios                   type=2[,manufacturer=str][,product=str][,ver‐
1918       sion=str][,serial=str][,asset=str][,location=str]
1919              Specify SMBIOS type 2 fields
1920
1921       -smbios                                 type=3[,manufacturer=str][,ver‐
1922       sion=str][,serial=str][,asset=str][,sku=str]
1923              Specify SMBIOS type 3 fields
1924
1925       -smbios                  type=4[,sock_pfx=str][,manufacturer=str][,ver‐
1926       sion=str][,serial=str][,asset=str][,part=str]
1927              Specify SMBIOS type 4 fields
1928
1929       -smbios                      type=17[,loc_pfx=str][,bank=str][,manufac‐
1930       turer=str][,serial=str][,asset=str][,part=str][,speed=%d]
1931              Specify SMBIOS type 17 fields
1932
1933   Network options
1934       -nic
1935       [tap|bridge|user|l2tpv3|vde|netmap|vhost-user|socket][,...][,mac=macaddr][,model=mn]
1936              This option is a shortcut  for  configuring  both  the  on-board
1937              (default) guest NIC hardware and the host network backend in one
1938              go.  The host backend options are the same as  with  the  corre‐
1939              sponding  -netdev  options below. The guest NIC model can be set
1940              with model=modelname.  Use  model=help  to  list  the  available
1941              device   types.  The  hardware  MAC  address  can  be  set  with
1942              mac=macaddr.
1943
1944              The following two example do exactly the same, to show how  -nic
1945              can be used to shorten the command line length:
1946
1947                 qemu-system-x86_64 -netdev user,id=n1,ipv6=off -device e1000,netdev=n1,mac=52:54:98:76:54:32
1948                 qemu-system-x86_64 -nic user,ipv6=off,model=e1000,mac=52:54:98:76:54:32
1949
1950       -nic none
1951              Indicate  that  no  network  devices should be configured. It is
1952              used to override the default  configuration  (default  NIC  with
1953              "user" host network backend) which is activated if no other net‐
1954              working options are provided.
1955
1956       -netdev user,id=id[,option][,option][,...]
1957              Configure user mode  host  network  backend  which  requires  no
1958              administrator privilege to run. Valid options are:
1959
1960              id=id  Assign symbolic name for use in monitor commands.
1961
1962              ipv4=on|off and ipv6=on|off
1963                     Specify that either IPv4 or IPv6 must be enabled. If nei‐
1964                     ther is specified both protocols are enabled.
1965
1966              net=addr[/mask]
1967                     Set IP network address the  guest  will  see.  Optionally
1968                     specify  the  netmask,  either  in the form a.b.c.d or as
1969                     number of valid top-most bits. Default is 10.0.2.0/24.
1970
1971              host=addr
1972                     Specify the guest-visible address of the host. Default is
1973                     the 2nd IP in the guest network, i.e. x.x.x.2.
1974
1975              ipv6-net=addr[/int]
1976                     Set  IPv6  network address the guest will see (default is
1977                     fec0::/64). The network prefix  is  given  in  the  usual
1978                     hexadecimal  IPv6  address  notation.  The prefix size is
1979                     optional, and is given as the number  of  valid  top-most
1980                     bits (default is 64).
1981
1982              ipv6-host=addr
1983                     Specify  the  guest-visible  IPv6  address  of  the host.
1984                     Default is the  2nd  IPv6  in  the  guest  network,  i.e.
1985                     xxxx::2.
1986
1987              restrict=on|off
1988                     If  this  option  is enabled, the guest will be isolated,
1989                     i.e. it will not be able to contact the host and no guest
1990                     IP  packets  will be routed over the host to the outside.
1991                     This option does not affect any explicitly set forwarding
1992                     rules.
1993
1994              hostname=name
1995                     Specifies  the  client  hostname reported by the built-in
1996                     DHCP server.
1997
1998              dhcpstart=addr
1999                     Specify the first of the 16 IPs the built-in DHCP  server
2000                     can  assign.  Default is the 15th to 31st IP in the guest
2001                     network, i.e. x.x.x.15 to x.x.x.31.
2002
2003              dns=addr
2004                     Specify the guest-visible address of  the  virtual  name‐
2005                     server.  The  address  must  be  different  from the host
2006                     address. Default is the 3rd IP in the guest network, i.e.
2007                     x.x.x.3.
2008
2009              ipv6-dns=addr
2010                     Specify  the  guest-visible  address  of the IPv6 virtual
2011                     nameserver. The address must be different from  the  host
2012                     address.   Default  is  the  3rd IP in the guest network,
2013                     i.e. xxxx::3.
2014
2015              dnssearch=domain
2016                     Provides an entry for the domain-search list sent by  the
2017                     built-in  DHCP server. More than one domain suffix can be
2018                     transmitted by specifying this option multiple times.  If
2019                     supported, this will cause the guest to automatically try
2020                     to append the given domain suffix(es) in  case  a  domain
2021                     name can not be resolved.
2022
2023                     Example:
2024
2025                        qemu-system-x86_64 -nic user,dnssearch=mgmt.example.org,dnssearch=example.org
2026
2027              domainname=domain
2028                     Specifies the client domain name reported by the built-in
2029                     DHCP server.
2030
2031              tftp=dir
2032                     When using  the  user  mode  network  stack,  activate  a
2033                     built-in TFTP server. The files in dir will be exposed as
2034                     the root of a TFTP server. The TFTP client on  the  guest
2035                     must be configured in binary mode (use the command bin of
2036                     the Unix TFTP client).
2037
2038              tftp-server-name=name
2039                     In BOOTP reply, broadcast name as the "TFTP server  name"
2040                     (RFC2132 option 66). This can be used to advise the guest
2041                     to load boot files or  configurations  from  a  different
2042                     server than the host address.
2043
2044              bootfile=file
2045                     When using the user mode network stack, broadcast file as
2046                     the BOOTP filename. In conjunction with tftp, this can be
2047                     used to network boot a guest from a local directory.
2048
2049                     Example (using pxelinux):
2050
2051                        qemu-system-x86_64 -hda linux.img -boot n -device e1000,netdev=n1     -netdev user,id=n1,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
2052
2053              smb=dir[,smbserver=addr]
2054                     When  using  the  user  mode  network  stack,  activate a
2055                     built-in SMB server so that Windows OSes  can  access  to
2056                     the  host  files  in dir transparently. The IP address of
2057                     the SMB server can be set to addr. By default the 4th  IP
2058                     in the guest network is used, i.e. x.x.x.4.
2059
2060                     In the guest Windows OS, the line:
2061
2062                        10.0.2.4 smbserver
2063
2064                     must be added in the file C:\WINDOWS\LMHOSTS (for windows
2065                     9x/Me) or C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS  (Windows
2066                     NT/2000).
2067
2068                     Then dir can be accessed in \\smbserver\qemu.
2069
2070                     Note  that  a  SAMBA server must be installed on the host
2071                     OS.
2072
2073              hostfwd=[tcp|udp]:[hostaddr]:hostport-[guestaddr]:guestport
2074                     Redirect incoming TCP or UDP connections to the host port
2075                     hostport  to the guest IP address guestaddr on guest port
2076                     guestport. If guestaddr is not specified,  its  value  is
2077                     x.x.x.15  (default  first  address  given by the built-in
2078                     DHCP server). By specifying hostaddr,  the  rule  can  be
2079                     bound to a specific host interface. If no connection type
2080                     is set, TCP is used. This option can  be  given  multiple
2081                     times.
2082
2083                     For  example, to redirect host X11 connection from screen
2084                     1 to guest screen 0, use the following:
2085
2086                        # on the host
2087                        qemu-system-x86_64 -nic user,hostfwd=tcp:127.0.0.1:6001-:6000
2088                        # this host xterm should open in the guest X11 server
2089                        xterm -display :1
2090
2091                     To redirect telnet connections from  host  port  5555  to
2092                     telnet port on the guest, use the following:
2093
2094                        # on the host
2095                        qemu-system-x86_64 -nic user,hostfwd=tcp::5555-:23
2096                        telnet localhost 5555
2097
2098                     Then  when you use on the host telnet localhost 5555, you
2099                     connect to the guest telnet server.
2100
2101              guestfwd=[tcp]:server:port-dev;                           guest‐
2102              fwd=[tcp]:server:port-cmd:command
2103                     Forward guest TCP connections to the IP address server on
2104                     port port to the character device dev  or  to  a  program
2105                     executed  by cmd:command which gets spawned for each con‐
2106                     nection. This option can be given multiple times.
2107
2108                     You can either use a chardev directly and have  that  one
2109                     used  throughout  QEMU's  lifetime, like in the following
2110                     example:
2111
2112                        # open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever
2113                        # the guest accesses it
2114                        qemu-system-x86_64 -nic user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321
2115
2116                     Or you can execute a  command  on  every  TCP  connection
2117                     established by the guest, so that QEMU behaves similar to
2118                     an inetd process for that virtual server:
2119
2120                        # call "netcat 10.10.1.1 4321" on every TCP connection to 10.0.2.100:1234
2121                        # and connect the TCP stream to its stdin/stdout
2122                        qemu-system-x86_64 -nic  'user,id=n1,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321'
2123
2124       -netdev             tap,id=id[,fd=h][,ifname=name][,script=file][,down‐
2125       script=dfile][,br=bridge][,helper=helper]
2126              Configure a host TAP network backend with ID id.
2127
2128              Use  the  network  script  file  to configure it and the network
2129              script dfile to deconfigure it. If name is not provided, the  OS
2130              automatically provides one. The default network configure script
2131              is /etc/qemu-ifup and the default network deconfigure script  is
2132              /etc/qemu-ifdown.  Use  script=no  or  downscript=no  to disable
2133              script execution.
2134
2135              If running QEMU as an unprivileged user, use the network  helper
2136              helper  to  configure  the  TAP  interface  and attach it to the
2137              bridge.    The   default   network    helper    executable    is
2138              /path/to/qemu-bridge-helper  and  the  default  bridge device is
2139              br0.
2140
2141              fd=h can be used to specify the handle of an already opened host
2142              TAP interface.
2143
2144              Examples:
2145
2146                 #launch a QEMU instance with the default network script
2147                 qemu-system-x86_64 linux.img -nic tap
2148
2149                 #launch a QEMU instance with two NICs, each one connected
2150                 #to a TAP device
2151                 qemu-system-x86_64 linux.img         -netdev tap,id=nd0,ifname=tap0 -device e1000,netdev=nd0         -netdev tap,id=nd1,ifname=tap1 -device rtl8139,netdev=nd1
2152
2153                 #launch a QEMU instance with the default network helper to
2154                 #connect a TAP device to bridge br0
2155                 qemu-system-x86_64 linux.img -device virtio-net-pci,netdev=n1         -netdev tap,id=n1,"helper=/path/to/qemu-bridge-helper"
2156
2157       -netdev bridge,id=id[,br=bridge][,helper=helper]
2158              Connect a host TAP network interface to a host bridge device.
2159
2160              Use the network helper helper to configure the TAP interface and
2161              attach it to the bridge. The default network  helper  executable
2162              is  /path/to/qemu-bridge-helper and the default bridge device is
2163              br0.
2164
2165              Examples:
2166
2167                 #launch a QEMU instance with the default network helper to
2168                 #connect a TAP device to bridge br0
2169                 qemu-system-x86_64 linux.img -netdev bridge,id=n1 -device virtio-net,netdev=n1
2170
2171                 #launch a QEMU instance with the default network helper to
2172                 #connect a TAP device to bridge qemubr0
2173                 qemu-system-x86_64 linux.img -netdev bridge,br=qemubr0,id=n1 -device virtio-net,netdev=n1
2174
2175       -netdev socket,id=id[,fd=h][,listen=[host]:port][,connect=host:port]
2176              This host network backend can be used  to  connect  the  guest's
2177              network  to another QEMU virtual machine using a TCP socket con‐
2178              nection. If listen is specified, QEMU waits for incoming connec‐
2179              tions  on port (host is optional). connect is used to connect to
2180              another QEMU instance using the listen option. fd=h specifies an
2181              already opened TCP socket.
2182
2183              Example:
2184
2185                 # launch a first QEMU instance
2186                 qemu-system-x86_64 linux.img                  -device e1000,netdev=n1,mac=52:54:00:12:34:56                  -netdev socket,id=n1,listen=:1234
2187                 # connect the network of this instance to the network of the first instance
2188                 qemu-system-x86_64 linux.img                  -device e1000,netdev=n2,mac=52:54:00:12:34:57                  -netdev socket,id=n2,connect=127.0.0.1:1234
2189
2190       -netdev socket,id=id[,fd=h][,mcast=maddr:port[,localaddr=addr]]
2191              Configure  a  socket  host  network backend to share the guest's
2192              network traffic with another QEMU virtual machines using  a  UDP
2193              multicast  socket,  effectively making a bus for every QEMU with
2194              same multicast address maddr and port. NOTES:
2195
2196              1. Several QEMU can be running on different hosts and share same
2197                 bus (assuming correct multicast setup for these hosts).
2198
2199              2. mcast  support  is  compatible with User Mode Linux (argument
2200                 ethN=mcast), see http://user-mode-linux.sf.net.
2201
2202              3. Use fd=h to specify an already opened UDP multicast socket.
2203
2204              Example:
2205
2206                 # launch one QEMU instance
2207                 qemu-system-x86_64 linux.img                  -device e1000,netdev=n1,mac=52:54:00:12:34:56                  -netdev socket,id=n1,mcast=230.0.0.1:1234
2208                 # launch another QEMU instance on same "bus"
2209                 qemu-system-x86_64 linux.img                  -device e1000,netdev=n2,mac=52:54:00:12:34:57                  -netdev socket,id=n2,mcast=230.0.0.1:1234
2210                 # launch yet another QEMU instance on same "bus"
2211                 qemu-system-x86_64 linux.img                  -device e1000,netdev=n3,mac=52:54:00:12:34:58                  -netdev socket,id=n3,mcast=230.0.0.1:1234
2212
2213              Example (User Mode Linux compat.):
2214
2215                 # launch QEMU instance (note mcast address selected is UML's default)
2216                 qemu-system-x86_64 linux.img                  -device e1000,netdev=n1,mac=52:54:00:12:34:56                  -netdev socket,id=n1,mcast=239.192.168.1:1102
2217                 # launch UML
2218                 /path/to/linux ubd0=/path/to/root_fs eth0=mcast
2219
2220              Example (send packets from host's 1.2.3.4):
2221
2222                 qemu-system-x86_64 linux.img                  -device e1000,netdev=n1,mac=52:54:00:12:34:56                  -netdev socket,id=n1,mcast=239.192.168.1:1102,localaddr=1.2.3.4
2223
2224       -netdev    l2tpv3,id=id,src=srcaddr,dst=dstaddr[,srcport=srcport][,dst‐
2225       port=dstport],txsession=txsession[,rxsession=rxses‐
2226       sion][,ipv6][,udp][,cookie64][,counter][,pin‐
2227       counter][,txcookie=txcookie][,rxcookie=rxcookie][,offset=offset]
2228              Configure  a  L2TPv3  pseudowire  host  network  backend. L2TPv3
2229              (RFC3931) is a popular protocol to transport Ethernet (and other
2230              Layer  2)  data  frames  between  two  systems. It is present in
2231              routers, firewalls  and  the  Linux  kernel  (from  version  3.3
2232              onwards).
2233
2234              This  transport allows a VM to communicate to another VM, router
2235              or firewall directly.
2236
2237              src=srcaddr
2238                     source address (mandatory)
2239
2240              dst=dstaddr
2241                     destination address (mandatory)
2242
2243              udp    select udp encapsulation (default is ip).
2244
2245              srcport=srcport
2246                     source udp port.
2247
2248              dstport=dstport
2249                     destination udp port.
2250
2251              ipv6   force v6, otherwise defaults to v4.
2252
2253              rxcookie=rxcookie; txcookie=txcookie
2254                     Cookies are a weak form of security in the l2tpv3  speci‐
2255                     fication.  Their function is mostly to prevent misconfig‐
2256                     uration. By default they are 32 bit.
2257
2258              cookie64
2259                     Set cookie size to 64 bit instead of the default 32
2260
2261              counter=off
2262                     Force  a  'cut-down'  L2TPv3  with  no  counter   as   in
2263                     draft-mkonstan-l2tpext-keyed-ipv6-tunnel-00
2264
2265              pincounter=on
2266                     Work  around  broken  counter  handling in peer. This may
2267                     also help on networks which have packet reorder.
2268
2269              offset=offset
2270                     Add an extra offset between header and data
2271
2272              For example, to attach a VM running on host 4.3.2.1  via  L2TPv3
2273              to the bridge br-lan on the remote Linux host 1.2.3.4:
2274
2275                 # Setup tunnel on linux host using raw ip as encapsulation
2276                 # on 1.2.3.4
2277                 ip l2tp add tunnel remote 4.3.2.1 local 1.2.3.4 tunnel_id 1 peer_tunnel_id 1     encap udp udp_sport 16384 udp_dport 16384
2278                 ip l2tp add session tunnel_id 1 name vmtunnel0 session_id     0xFFFFFFFF peer_session_id 0xFFFFFFFF
2279                 ifconfig vmtunnel0 mtu 1500
2280                 ifconfig vmtunnel0 up
2281                 brctl addif br-lan vmtunnel0
2282
2283
2284                 # on 4.3.2.1
2285                 # launch QEMU instance - if your network has reorder or is very lossy add ,pincounter
2286
2287                 qemu-system-x86_64 linux.img -device e1000,netdev=n1     -netdev l2tpv3,id=n1,src=4.2.3.1,dst=1.2.3.4,udp,srcport=16384,dstport=16384,rxsession=0xffffffff,txsession=0xffffffff,counter
2288
2289       -netdev              vde,id=id[,sock=socketpath][,port=n][,group=group‐
2290       name][,mode=octalmode]
2291              Configure VDE backend to connect to PORT n of a vde switch  run‐
2292              ning  on  host and listening for incoming connections on socket‐
2293              path. Use GROUP groupname and MODE octalmode to  change  default
2294              ownership and permissions for communication port. This option is
2295              only available if  QEMU  has  been  compiled  with  vde  support
2296              enabled.
2297
2298              Example:
2299
2300                 # launch vde switch
2301                 vde_switch -F -sock /tmp/myswitch
2302                 # launch QEMU instance
2303                 qemu-system-x86_64 linux.img -nic vde,sock=/tmp/myswitch
2304
2305       -netdev vhost-user,chardev=id[,vhostforce=on|off][,queues=n]
2306              Establish  a  vhost-user  netdev,  backed  by  a chardev id. The
2307              chardev  should  be  a  unix  domain  socket  backed  one.   The
2308              vhost-user  uses  a  specifically defined protocol to pass vhost
2309              ioctl replacement messages to an application on the other end of
2310              the  socket.  On non-MSIX guests, the feature can be forced with
2311              vhostforce. Use 'queues=n' to specify the number of queues to be
2312              created for multiqueue vhost-user.
2313
2314              Example:
2315
2316                 qemu -m 512 -object memory-backend-file,id=mem,size=512M,mem-path=/hugetlbfs,share=on \
2317                      -numa node,memdev=mem \
2318                      -chardev socket,id=chr0,path=/path/to/socket \
2319                      -netdev type=vhost-user,id=net0,chardev=chr0 \
2320                      -device virtio-net-pci,netdev=net0
2321
2322       -netdev vhost-vdpa,vhostdev=/path/to/dev
2323              Establish a vhost-vdpa netdev.
2324
2325              vDPA device is a device that uses a datapath which complies with
2326              the virtio specifications with a vendor specific  control  path.
2327              vDPA  devices  can be both physically located on the hardware or
2328              emulated by software.
2329
2330       -netdev hubport,id=id,hubid=hubid[,netdev=nd]
2331              Create a hub port on the emulated hub with ID hubid.
2332
2333              The hubport netdev lets you connect a NIC to a QEMU emulated hub
2334              instead  of a single netdev. Alternatively, you can also connect
2335              the hubport to another netdev with ID nd by using the  netdev=nd
2336              option.
2337
2338       -net                         nic[,netdev=nd][,macaddr=mac][,model=type]
2339       [,name=name][,addr=addr][,vectors=v]
2340              Legacy option to configure or create  an  on-board  (or  machine
2341              default)  Network  Interface  Card(NIC) and connect it either to
2342              the emulated hub with ID 0 (i.e. the default  hub),  or  to  the
2343              netdev  nd.   If  model  is  omitted, then the default NIC model
2344              associated with the machine type is used. Note that the  default
2345              NIC  model  may  change in future QEMU releases, so it is highly
2346              recommended to always  specify  a  model.  Optionally,  the  MAC
2347              address  can  be  changed to mac, the device address set to addr
2348              (PCI cards only), and a name can be assigned for use in  monitor
2349              commands.  Optionally, for PCI cards, you can specify the number
2350              v of MSI-X vectors that the card should have; this  option  cur‐
2351              rently only affects virtio cards; set v = 0 to disable MSI-X. If
2352              no -net option is specified, a single NIC is created.  QEMU  can
2353              emulate  several  different  models  of  network card.  Use -net
2354              nic,model=help for a list of available devices for your target.
2355
2356       -net user|tap|bridge|socket|l2tpv3|vde[,...][,name=name]
2357              Configure a host network backend (with the options corresponding
2358              to the same -netdev option) and connect it to the emulated hub 0
2359              (the default hub). Use name to specify the name of the hub port.
2360
2361   Character device options
2362       The general form of a character device option is:
2363
2364       -chardev backend,id=id[,mux=on|off][,options]
2365              Backend is one of: null,  socket,  udp,  msmouse,  vc,  ringbuf,
2366              file, pipe, console, serial, pty, stdio, braille, tty, parallel,
2367              parport, spicevmc, spiceport. The specific backend  will  deter‐
2368              mine the applicable options.
2369
2370              Use -chardev help to print all available chardev backend types.
2371
2372              All  devices  must have an id, which can be any string up to 127
2373              characters long. It is used to uniquely identify this device  in
2374              other command line directives.
2375
2376              A  character device may be used in multiplexing mode by multiple
2377              front-ends. Specify mux=on to enable this mode. A multiplexer is
2378              a  "1:N"  device, and here the "1" end is your specified chardev
2379              backend, and the "N" end is the various parts of QEMU  that  can
2380              talk  to  a  chardev.  If  you create a chardev with id=myid and
2381              mux=on, QEMU will create a multiplexer with your  specified  ID,
2382              and  you  can  then  configure  multiple  front ends to use that
2383              chardev ID for their input/output. Up to  four  different  front
2384              ends  can be connected to a single multiplexed chardev. (Without
2385              multiplexing enabled, a chardev can only be  used  by  a  single
2386              front  end.)  For  instance you could use this to allow a single
2387              stdio chardev to be used by two serial ports and the QEMU  moni‐
2388              tor:
2389
2390                 -chardev stdio,mux=on,id=char0 \
2391                 -mon chardev=char0,mode=readline \
2392                 -serial chardev:char0 \
2393                 -serial chardev:char0
2394
2395              You  can  have  more than one multiplexer in a system configura‐
2396              tion; for instance you could have a TCP port multiplexed between
2397              UART  0 and UART 1, and stdio multiplexed between the QEMU moni‐
2398              tor and a parallel port:
2399
2400                 -chardev stdio,mux=on,id=char0 \
2401                 -mon chardev=char0,mode=readline \
2402                 -parallel chardev:char0 \
2403                 -chardev tcp,...,mux=on,id=char1 \
2404                 -serial chardev:char1 \
2405                 -serial chardev:char1
2406
2407              When you're using a multiplexed character  device,  some  escape
2408              sequences are interpreted in the input. See mux_005fkeys.
2409
2410              Note  that some other command line options may implicitly create
2411              multiplexed character backends; for instance  -serial  mon:stdio
2412              creates a multiplexed stdio backend connected to the serial port
2413              and the QEMU monitor, and -nographic also multiplexes  the  con‐
2414              sole and the monitor to stdio.
2415
2416              There  is  currently  no  support  for multiplexing in the other
2417              direction (where a single QEMU front end takes input and  output
2418              from multiple chardevs).
2419
2420              Every  backend  supports  the logfile option, which supplies the
2421              path to a file to record all data transmitted via  the  backend.
2422              The logappend option controls whether the log file will be trun‐
2423              cated or appended to when opened.
2424
2425       The available backends are:
2426
2427       -chardev null,id=id
2428              A void device. This device will not emit any data, and will drop
2429              any  data  it  receives.  The  null  backend  does  not take any
2430              options.
2431
2432       -chardev        socket,id=id[,TCP        options        or         unix
2433       options][,server][,nowait][,telnet][,websocket][,reconnect=sec‐
2434       onds][,tls-creds=id][,tls-authz=id]
2435              Create a two-way stream socket, which can be either a TCP  or  a
2436              unix socket. A unix socket will be created if path is specified.
2437              Behaviour is undefined if TCP options are specified for  a  unix
2438              socket.
2439
2440              server specifies that the socket shall be a listening socket.
2441
2442              nowait specifies that QEMU should not block waiting for a client
2443              to connect to a listening socket.
2444
2445              telnet specifies that traffic on  the  socket  should  interpret
2446              telnet escape sequences.
2447
2448              websocket  specifies that the socket uses WebSocket protocol for
2449              communication.
2450
2451              reconnect sets the timeout for reconnecting on non-server  sock‐
2452              ets  when  the  remote  end goes away. qemu will delay this many
2453              seconds and then attempt to reconnect. Zero disables  reconnect‐
2454              ing, and is the default.
2455
2456              tls-creds  requests  enablement  of the TLS protocol for encryp‐
2457              tion, and specifies the id of the TLS credentials to use for the
2458              handshake.  The  credentials must be previously created with the
2459              -object tls-creds argument.
2460
2461              tls-auth provides the ID  of  the  QAuthZ  authorization  object
2462              against which the client's x509 distinguished name will be vali‐
2463              dated. This object is only resolved at time of use,  so  can  be
2464              deleted  and  recreated  on  the fly while the chardev server is
2465              active.  If missing, it will default to denying access.
2466
2467              TCP and unix socket options are given below:
2468
2469              TCP options:  port=port[,host=host][,to=to][,ipv4][,ipv6][,node‐
2470              lay]
2471                     host  for  a listening socket specifies the local address
2472                     to be bound. For a connecting socket species  the  remote
2473                     host  to connect to. host is optional for listening sock‐
2474                     ets. If not specified it defaults to 0.0.0.0.
2475
2476                     port for a listening socket specifies the local  port  to
2477                     be  bound.  For a connecting socket specifies the port on
2478                     the remote host to connect  to.  port  can  be  given  as
2479                     either a port number or a service name. port is required.
2480
2481                     to is only relevant to listening sockets. If it is speci‐
2482                     fied, and port cannot be bound, QEMU will attempt to bind
2483                     to  subsequent ports up to and including to until it suc‐
2484                     ceeds. to must be specified as a port number.
2485
2486                     ipv4 and ipv6 specify that either IPv4 or  IPv6  must  be
2487                     used.  If  neither is specified the socket may use either
2488                     protocol.
2489
2490                     nodelay disables the Nagle algorithm.
2491
2492              unix options: path=path[,abstract=on|off][,tight=on|off]
2493                     path specifies the local path of the unix socket. path is
2494                     required.   abstract  specifies  the  use of the abstract
2495                     socket namespace, rather than the filesystem.   Optional,
2496                     defaults  to  false.   tight  sets  the  socket length of
2497                     abstract sockets to their minimum, rather than  the  full
2498                     sun_path length.  Optional, defaults to true.
2499
2500       -chardev  udp,id=id[,host=host],port=port[,localaddr=localaddr][,local‐
2501       port=localport][,ipv4][,ipv6]
2502              Sends all traffic from the guest to a remote host over UDP.
2503
2504              host specifies the remote host to connect to. If  not  specified
2505              it defaults to localhost.
2506
2507              port  specifies the port on the remote host to connect to.  port
2508              is required.
2509
2510              localaddr specifies the local address to bind to. If not  speci‐
2511              fied it defaults to 0.0.0.0.
2512
2513              localport  specifies the local port to bind to. If not specified
2514              any available local port will be used.
2515
2516              ipv4 and ipv6 specify that either IPv4 or IPv6 must be used.  If
2517              neither is specified the device may use either protocol.
2518
2519       -chardev msmouse,id=id
2520              Forward  QEMU's  emulated  msmouse  events to the guest. msmouse
2521              does not take any options.
2522
2523       -chardev
2524       vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]
2525              Connect  to  a  QEMU  text console. vc may optionally be given a
2526              specific size.
2527
2528              width and height specify the width and  height  respectively  of
2529              the console, in pixels.
2530
2531              cols  and  rows  specify that the console be sized to fit a text
2532              console with the given dimensions.
2533
2534       -chardev ringbuf,id=id[,size=size]
2535              Create a ring buffer with fixed size size. size must be a  power
2536              of two and defaults to 64K.
2537
2538       -chardev file,id=id,path=path
2539              Log all traffic received from the guest to a file.
2540
2541              path specifies the path of the file to be opened. This file will
2542              be created if it does not already exist, and overwritten  if  it
2543              does.  path is required.
2544
2545       -chardev pipe,id=id,path=path
2546              Create  a two-way connection to the guest. The behaviour differs
2547              slightly between Windows hosts and other hosts:
2548
2549              On  Windows,  a  single  duplex  pipe   will   be   created   at
2550              \\.pipe\path.
2551
2552              On  other  hosts,  2  pipes  will  be created called path.in and
2553              path.out. Data written to path.in will be received by the guest.
2554              Data  written  by the guest can be read from path.out. QEMU will
2555              not create these fifos, and requires them to be present.
2556
2557              path forms part of the pipe path as  described  above.  path  is
2558              required.
2559
2560       -chardev console,id=id
2561              Send  traffic  from the guest to QEMU's standard output. console
2562              does not take any options.
2563
2564              console is only available on Windows hosts.
2565
2566       -chardev serial,id=id,path=path
2567              Send traffic from the guest to a serial device on the host.
2568
2569              On Unix hosts serial will actually accept any  tty  device,  not
2570              only serial lines.
2571
2572              path specifies the name of the serial device to open.
2573
2574       -chardev pty,id=id
2575              Create  a new pseudo-terminal on the host and connect to it. pty
2576              does not take any options.
2577
2578              pty is not available on Windows hosts.
2579
2580       -chardev stdio,id=id[,signal=on|off]
2581              Connect to standard  input  and  standard  output  of  the  QEMU
2582              process.
2583
2584              signal  controls  if  signals  are enabled on the terminal, that
2585              includes exiting QEMU with  the  key  sequence  Control-c.  This
2586              option is enabled by default, use signal=off to disable it.
2587
2588       -chardev braille,id=id
2589              Connect  to  a  local  BrlAPI  server. braille does not take any
2590              options.
2591
2592       -chardev tty,id=id,path=path
2593              tty is only available on Linux, Sun,  FreeBSD,  NetBSD,  OpenBSD
2594              and DragonFlyBSD hosts. It is an alias for serial.
2595
2596              path specifies the path to the tty. path is required.
2597
2598       -chardev parallel,id=id,path=path
2599
2600
2601       -chardev parport,id=id,path=path
2602              parallel  is  only  available on Linux, FreeBSD and DragonFlyBSD
2603              hosts.
2604
2605              Connect to a local parallel port.
2606
2607              path specifies the path to the parallel  port  device.  path  is
2608              required.
2609
2610       -chardev spicevmc,id=id,debug=debug,name=name
2611              spicevmc is only available when spice support is built in.
2612
2613              debug debug level for spicevmc
2614
2615              name name of spice channel to connect to
2616
2617              Connect to a spice virtual machine channel, such as vdiport.
2618
2619       -chardev spiceport,id=id,debug=debug,name=name
2620              spiceport is only available when spice support is built in.
2621
2622              debug debug level for spicevmc
2623
2624              name name of spice port to connect to
2625
2626              Connect  to  a spice port, allowing a Spice client to handle the
2627              traffic identified by a name (preferably a fqdn).
2628
2629   TPM device options
2630       The general form of a TPM device option is:
2631
2632       -tpmdev backend,id=id[,options]
2633              The specific backend type will determine the applicable options.
2634              The  -tpmdev  option  creates  the  TPM  backend  and requires a
2635              -device option that specifies the TPM frontend interface model.
2636
2637              Use -tpmdev help to print all available TPM backend types.
2638
2639       The available backends are:
2640
2641       -tpmdev passthrough,id=id,path=path,cancel-path=cancel-path
2642              (Linux-host only) Enable access to  the  host's  TPM  using  the
2643              passthrough driver.
2644
2645              path  specifies  the  path  to the host's TPM device, i.e., on a
2646              Linux host this would be /dev/tpm0.  path  is  optional  and  by
2647              default /dev/tpm0 is used.
2648
2649              cancel-path  specifies  the  path to the host TPM device's sysfs
2650              entry allowing for cancellation of an ongoing TPM command.  can‐
2651              cel-path  is  optional  and  by default QEMU will search for the
2652              sysfs entry to use.
2653
2654              Some notes about using  the  host's  TPM  with  the  passthrough
2655              driver:
2656
2657              The  TPM  device  accessed by the passthrough driver must not be
2658              used by any other application on the host.
2659
2660              Since the host's firmware (BIOS/UEFI)  has  already  initialized
2661              the  TPM, the VM's firmware (BIOS/UEFI) will not be able to ini‐
2662              tialize the TPM again and may therefore not show a  TPM-specific
2663              menu  that  would otherwise allow the user to configure the TPM,
2664              e.g., allow the user to  enable/disable  or  activate/deactivate
2665              the  TPM. Further, if TPM ownership is released from within a VM
2666              then the host's TPM will get disabled and deactivated. To enable
2667              and  activate  the  TPM  again  afterwards,  the  host has to be
2668              rebooted and the user is required to enter the  firmware's  menu
2669              to  enable  and  activate  the  TPM. If the TPM is left disabled
2670              and/or deactivated most TPM commands will fail.
2671
2672              To create a passthrough TPM use the following two options:
2673
2674                 -tpmdev passthrough,id=tpm0 -device tpm-tis,tpmdev=tpm0
2675
2676              Note  that  the  -tpmdev  id  is  tpm0  and  is  referenced   by
2677              tpmdev=tpm0 in the device option.
2678
2679       -tpmdev emulator,id=id,chardev=dev
2680              (Linux-host  only)  Enable  access  to a TPM emulator using Unix
2681              domain socket based chardev backend.
2682
2683              chardev specifies the unique ID of a  character  device  backend
2684              that provides connection to the software TPM server.
2685
2686              To  create  a  TPM  emulator  backend device with chardev socket
2687              backend:
2688
2689                 -chardev socket,id=chrtpm,path=/tmp/swtpm-sock -tpmdev emulator,id=tpm0,chardev=chrtpm -device tpm-tis,tpmdev=tpm0
2690
2691   Linux/Multiboot boot specific
2692       When using these options, you can use a given Linux or Multiboot kernel
2693       without  installing  it  in the disk image. It can be useful for easier
2694       testing of various kernels.
2695
2696       -kernel bzImage
2697              Use bzImage as kernel image. The kernel can be  either  a  Linux
2698              kernel or in multiboot format.
2699
2700       -append cmdline
2701              Use cmdline as kernel command line
2702
2703       -initrd file
2704              Use file as initial ram disk.
2705
2706       -initrd file1 arg=foo,file2
2707              This syntax is only available with multiboot.
2708
2709              Use  file1 and file2 as modules and pass arg=foo as parameter to
2710              the first module.
2711
2712       -dtb file
2713              Use file as a device tree binary (dtb) image and pass it to  the
2714              kernel on boot.
2715
2716   Debug/Expert options
2717       -fw_cfg [name=]name,file=file
2718              Add named fw_cfg entry with contents from file file.
2719
2720       -fw_cfg [name=]name,string=str
2721              Add named fw_cfg entry with contents from string str.
2722
2723              The terminating NUL character of the contents of str will not be
2724              included as part of the fw_cfg item  data.  To  insert  contents
2725              with  embedded  NUL characters, you have to use the file parame‐
2726              ter.
2727
2728              The fw_cfg entries are passed by QEMU through to the guest.
2729
2730              Example:
2731
2732                 -fw_cfg name=opt/com.mycompany/blob,file=./my_blob.bin
2733
2734              creates an fw_cfg entry named opt/com.mycompany/blob  with  con‐
2735              tents from ./my_blob.bin.
2736
2737       -serial dev
2738              Redirect  the  virtual serial port to host character device dev.
2739              The default device is vc in graphical  mode  and  stdio  in  non
2740              graphical mode.
2741
2742              This option can be used several times to simulate up to 4 serial
2743              ports.
2744
2745              Use -serial none to disable all serial ports.
2746
2747              Available character devices are:
2748
2749              vc[:WxH]
2750                     Virtual console. Optionally, a width and  height  can  be
2751                     given in pixel with
2752
2753                        vc:800x600
2754
2755                     It is also possible to specify width or height in charac‐
2756                     ters:
2757
2758                        vc:80Cx24C
2759
2760              pty    [Linux only] Pseudo TTY (a new PTY is automatically allo‐
2761                     cated)
2762
2763              none   No device is allocated.
2764
2765              null   void device
2766
2767              chardev:id
2768                     Use  a  named  character device defined with the -chardev
2769                     option.
2770
2771              /dev/XXX
2772                     [Linux only] Use host  tty,  e.g.  /dev/ttyS0.  The  host
2773                     serial  port parameters are set according to the emulated
2774                     ones.
2775
2776              /dev/parportN
2777                     [Linux only, parallel port only] Use host  parallel  port
2778                     N.   Currently  SPP and EPP parallel port features can be
2779                     used.
2780
2781              file:filename
2782                     Write output to filename. No character can be read.
2783
2784              stdio  [Unix only] standard input/output
2785
2786              pipe:filename
2787                     name pipe filename
2788
2789              COMn   [Windows only] Use host serial port n
2790
2791              udp:[remote_host]:remote_port[@[src_ip]:src_port]
2792                     This implements UDP  Net  Console.  When  remote_host  or
2793                     src_ip  are  not  specified they default to 0.0.0.0. When
2794                     not using a specified src_port a random port is automati‐
2795                     cally chosen.
2796
2797                     If  you  just  want a simple readonly console you can use
2798                     netcat or nc, by starting QEMU  with:  -serial  udp::4555
2799                     and  nc  as: nc -u -l -p 4555. Any time QEMU writes some‐
2800                     thing to that port it will appear in the netconsole  ses‐
2801                     sion.
2802
2803                     If you plan to send characters back via netconsole or you
2804                     want to stop and start QEMU a lot of  times,  you  should
2805                     have  QEMU  use  the  same source port each time by using
2806                     something like -serial udp::4555@:4556 to  QEMU.  Another
2807                     approach  is to use a patched version of netcat which can
2808                     listen to a TCP port and send and receive characters  via
2809                     udp.  If you have a patched version of netcat which acti‐
2810                     vates telnet remote echo and single char  transfer,  then
2811                     you  can  use  the  following  options to set up a netcat
2812                     redirector to allow telnet on port  5555  to  access  the
2813                     QEMU port.
2814
2815                     QEMU Options:
2816                            -serial udp::4555@:4556
2817
2818                     netcat options:
2819                            -u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T
2820
2821                     telnet options:
2822                            localhost 5555
2823
2824              tcp:[host]:port[,server][,nowait][,nodelay][,reconnect=seconds]
2825                     The  TCP  Net  Console has two modes of operation. It can
2826                     send the serial I/O to a location or wait for  a  connec‐
2827                     tion  from  a location. By default the TCP Net Console is
2828                     sent to host at the port. If you use  the  server  option
2829                     QEMU will wait for a client socket application to connect
2830                     to the port before continuing, unless the  nowait  option
2831                     was  specified.  The  nodelay  option  disables the Nagle
2832                     buffering algorithm. The reconnect option only applies if
2833                     noserver  is  set,  if  the  connection goes down it will
2834                     attempt to reconnect at the given interval.  If  host  is
2835                     omitted, 0.0.0.0 is assumed. Only one TCP connection at a
2836                     time is accepted. You can use telnet to  connect  to  the
2837                     corresponding character device.
2838
2839                     Example to send tcp console to 192.168.0.2 port 4444
2840                            -serial tcp:192.168.0.2:4444
2841
2842                     Example to listen and wait on port 4444 for connection
2843                            -serial tcp::4444,server
2844
2845                     Example  to  not wait and listen on ip 192.168.0.100 port
2846                     4444
2847                            -serial tcp:192.168.0.100:4444,server,nowait
2848
2849              telnet:host:port[,server][,nowait][,nodelay]
2850                     The telnet protocol is used instead of raw  tcp  sockets.
2851                     The options work the same as if you had specified -serial
2852                     tcp.  The difference is that the port acts like a  telnet
2853                     server  or  client  using telnet option negotiation. This
2854                     will also allow you to send the MAGIC_SYSRQ  sequence  if
2855                     you   use  a  telnet  that  supports  sending  the  break
2856                     sequence. Typically in unix telnet you do  it  with  Con‐
2857                     trol-]  and  then  type "send break" followed by pressing
2858                     the enter key.
2859
2860              websocket:host:port,server[,nowait][,nodelay]
2861                     The WebSocket protocol is used instead of raw tcp socket.
2862                     The  port  acts as a WebSocket server. Client mode is not
2863                     supported.
2864
2865              unix:path[,server][,nowait][,reconnect=seconds]
2866                     A unix domain socket is used instead of a tcp socket. The
2867                     option works the same as if you had specified -serial tcp
2868                     except the unix domain socket path is  used  for  connec‐
2869                     tions.
2870
2871              mon:dev_string
2872                     This  is a special option to allow the monitor to be mul‐
2873                     tiplexed  onto  another  serial  port.  The  monitor   is
2874                     accessed with key sequence of Control-a and then pressing
2875                     c. dev_string should be any one  of  the  serial  devices
2876                     specified above. An example to multiplex the monitor onto
2877                     a telnet server listening on port 4444 would be:
2878
2879                     -serial mon:telnet::4444,server,nowait
2880
2881                     When the monitor is multiplexed to  stdio  in  this  way,
2882                     Ctrl+C  will  not  terminate  QEMU  any  more but will be
2883                     passed to the guest instead.
2884
2885              braille
2886                     Braille device. This  will  use  BrlAPI  to  display  the
2887                     braille output on a real or fake device.
2888
2889              msmouse
2890                     Three button serial mouse. Configure the guest to use Mi‐
2891                     crosoft protocol.
2892
2893       -parallel dev
2894              Redirect the virtual parallel port  to  host  device  dev  (same
2895              devices  as  the serial port). On Linux hosts, /dev/parportN can
2896              be used to use hardware devices connected on  the  corresponding
2897              host parallel port.
2898
2899              This option can be used several times to simulate up to 3 paral‐
2900              lel ports.
2901
2902              Use -parallel none to disable all parallel ports.
2903
2904       -monitor dev
2905              Redirect the monitor to host device dev  (same  devices  as  the
2906              serial  port).  The  default  device is vc in graphical mode and
2907              stdio in non graphical mode. Use -monitor none  to  disable  the
2908              default monitor.
2909
2910       -qmp dev
2911              Like -monitor but opens in 'control' mode.
2912
2913       -qmp-pretty dev
2914              Like -qmp but uses pretty JSON formatting.
2915
2916       -mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]
2917              Setup  monitor  on  chardev  name.  pretty  turns on JSON pretty
2918              printing easing human reading and debugging.
2919
2920       -debugcon dev
2921              Redirect the debug console to host device dev (same  devices  as
2922              the serial port). The debug console is an I/O port which is typ‐
2923              ically port 0xe9; writing to that I/O port sends output to  this
2924              device.  The default device is vc in graphical mode and stdio in
2925              non graphical mode.
2926
2927       -pidfile file
2928              Store the QEMU process PID in file. It is useful if  you  launch
2929              QEMU from a script.
2930
2931       -singlestep
2932              Run the emulation in single step mode.
2933
2934       --preconfig
2935              Pause  QEMU  for interactive configuration before the machine is
2936              created, which allows querying and configuring  properties  that
2937              will affect machine initialization. Use QMP command 'x-exit-pre‐
2938              config' to exit the preconfig state and move to the  next  state
2939              (i.e.  run guest if -S isn't used or pause the second time if -S
2940              is used). This option is experimental.
2941
2942       -S     Do not start CPU at startup (you must type 'c' in the monitor).
2943
2944       -realtime mlock=on|off
2945              Run qemu with realtime features. mlocking qemu and guest  memory
2946              can be enabled via mlock=on (enabled by default).
2947
2948       -overcommit mem-lock=on|off
2949
2950
2951       -overcommit cpu-pm=on|off
2952              Run  qemu with hints about host resource overcommit. The default
2953              is to assume that host overcommits all resources.
2954
2955              Locking qemu and guest memory can  be  enabled  via  mem-lock=on
2956              (disabled  by default). This works when host memory is not over‐
2957              committed and reduces the worst-case latency for guest. This  is
2958              equivalent to realtime.
2959
2960              Guest  ability  to  manage  power state of host cpus (increasing
2961              latency for other processes on the same host cpu, but decreasing
2962              latency  for  guest)  can  be enabled via cpu-pm=on (disabled by
2963              default). This works best when host CPU  is  not  overcommitted.
2964              When  used,  host  estimates  of CPU cycle and power utilization
2965              will be incorrect, not taking into account guest idle time.
2966
2967       -gdb dev
2968              Accept a gdb connection on device dev (see gdb_005fusage).  Note
2969              that  this  option  does not pause QEMU execution -- if you want
2970              QEMU to not start the guest until you connect with gdb and issue
2971              a  continue command, you will need to also pass the -S option to
2972              QEMU.
2973
2974              The most usual configuration is to listen on a local TCP socket:
2975
2976                 -gdb tcp::3117
2977
2978              but you can specify other backends; UDP,  pseudo  TTY,  or  even
2979              stdio are all reasonable use cases. For example, a stdio connec‐
2980              tion allows you to start QEMU from within gdb and establish  the
2981              connection via a pipe:
2982
2983                 (gdb) target remote | exec qemu-system-x86_64 -gdb stdio ...
2984
2985       -s     Shorthand  for -gdb tcp::1234, i.e. open a gdbserver on TCP port
2986              1234 (see gdb_005fusage).
2987
2988       -d item1[,...]
2989              Enable logging of specified items. Use '-d help' for a  list  of
2990              log items.
2991
2992       -D logfile
2993              Output log in logfile instead of to stderr
2994
2995       -dfilter range1[,...]
2996              Filter  debug  output  to  that  relevant  to  a range of target
2997              addresses.  The filter spec can be either start+size, start-size
2998              or  start..end  where  start  end and size are the addresses and
2999              sizes required. For example:
3000
3001                 -dfilter 0x8000..0x8fff,0xffffffc000080000+0x200,0xffffffc000060000-0x1000
3002
3003              Will dump output for any code in the 0x1000 sized block starting
3004              at    0x8000   and   the   0x200   sized   block   starting   at
3005              0xffffffc000080000 and another 0x1000 sized  block  starting  at
3006              0xffffffc00005f000.
3007
3008       -seed number
3009              Force the guest to use a deterministic pseudo-random number gen‐
3010              erator, seeded with number. This does not affect crypto routines
3011              within the host.
3012
3013       -L path
3014              Set the directory for the BIOS, VGA BIOS and keymaps.
3015
3016              To list all the data directories, use -L help.
3017
3018       -bios file
3019              Set the filename for the BIOS.
3020
3021       -enable-kvm
3022              Enable  KVM  full  virtualization  support.  This option is only
3023              available if KVM support is enabled when compiling.
3024
3025       -xen-domid id
3026              Specify xen guest domain id (XEN only).
3027
3028       -xen-attach
3029              Attach to existing xen domain. libxl will use this when starting
3030              QEMU  (XEN  only).  Restrict  set of available xen operations to
3031              specified domain id (XEN only).
3032
3033       -no-reboot
3034              Exit instead of rebooting.
3035
3036       -no-shutdown
3037              Don't exit QEMU on guest shutdown, but  instead  only  stop  the
3038              emulation. This allows for instance switching to monitor to com‐
3039              mit changes to the disk image.
3040
3041       -loadvm file
3042              Start right away with a saved state (loadvm in monitor)
3043
3044       -daemonize
3045              Daemonize the QEMU process after initialization. QEMU  will  not
3046              detach from standard IO until it is ready to receive connections
3047              on any of its devices. This option is a useful way for  external
3048              programs  to launch QEMU without having to cope with initializa‐
3049              tion race conditions.
3050
3051       -option-rom file
3052              Load the contents of file as an option ROM. This option is  use‐
3053              ful to load things like EtherBoot.
3054
3055       -rtc           [base=utc|localtime|datetime][,clock=host|rt|vm][,drift‐
3056       fix=none|slew]
3057              Specify base as utc or localtime to let the  RTC  start  at  the
3058              current  UTC  or local time, respectively. localtime is required
3059              for correct date in MS-DOS or Windows. To start  at  a  specific
3060              point    in    time,    provide    datetime    in   the   format
3061              2006-06-17T16:01:21 or 2006-06-17. The default base is UTC.
3062
3063              By default the RTC is driven  by  the  host  system  time.  This
3064              allows  using  of the RTC as accurate reference clock inside the
3065              guest, specifically if the host time is  smoothly  following  an
3066              accurate  external reference clock, e.g. via NTP. If you want to
3067              isolate the guest time from the host, you can set  clock  to  rt
3068              instead,  which  provides a host monotonic clock if host support
3069              it. To even prevent the RTC from progressing during  suspension,
3070              you  can  set  clock to vm (virtual clock). 'clock=vm' is recom‐
3071              mended especially in icount mode in order to preserve  determin‐
3072              ism;  however, note that in icount mode the speed of the virtual
3073              clock is variable and can in general differ from the host clock.
3074
3075              Enable driftfix (i386 targets only) if you experience time drift
3076              problems,  specifically with Windows' ACPI HAL. This option will
3077              try to figure out how many timer interrupts were  not  processed
3078              by the Windows guest and will re-inject them.
3079
3080       -icount        [shift=N|auto][,rr=record|replay,rrfile=filename,rrsnap‐
3081       shot=snapshot]
3082              Enable virtual instruction counter. The virtual cpu will execute
3083              one  instruction every 2^N ns of virtual time. If auto is speci‐
3084              fied then the virtual cpu speed will be  automatically  adjusted
3085              to keep virtual time within a few seconds of real time.
3086
3087              When  the virtual cpu is sleeping, the virtual time will advance
3088              at  default  speed  unless  sleep=on|off  is   specified.   With
3089              sleep=on|off, the virtual time will jump to the next timer dead‐
3090              line instantly whenever the virtual cpu goes to sleep  mode  and
3091              will  not  advance  if  no  timer is enabled. This behavior give
3092              deterministic execution times from the guest point of view.
3093
3094              Note that while this option can give deterministic behavior,  it
3095              does  not  provide cycle accurate emulation. Modern CPUs contain
3096              superscalar out of order cores with complex  cache  hierarchies.
3097              The  number of instructions executed often has little or no cor‐
3098              relation with actual performance.
3099
3100              align=on will activate the delay algorithm  which  will  try  to
3101              synchronise the host clock and the virtual clock. The goal is to
3102              have a guest running at the real frequency imposed by the  shift
3103              option. Whenever the guest clock is behind the host clock and if
3104              align=on is specified then we print a message  to  the  user  to
3105              inform about the delay. Currently this option does not work when
3106              shift is auto. Note: The sync  algorithm  will  work  for  those
3107              shift  values  for  which the guest clock runs ahead of the host
3108              clock.  Typically this happens when the shift value is high (how
3109              high depends on the host machine).
3110
3111              When  rr  option  is  specified  deterministic  record/replay is
3112              enabled. Replay log is written into filename file in record mode
3113              and read from this file in replay mode.
3114
3115              Option  rrsnapshot is used to create new vm snapshot named snap‐
3116              shot at the start of execution recording. In  replay  mode  this
3117              option is used to load the initial VM state.
3118
3119       -watchdog model
3120              Create  a  virtual  hardware watchdog device. Once enabled (by a
3121              guest action), the watchdog must be periodically  polled  by  an
3122              agent  inside  the  guest  or  else the guest will be restarted.
3123              Choose a model for which your guest has drivers.
3124
3125              The model is the model of  hardware  watchdog  to  emulate.  Use
3126              -watchdog  help  to  list  available  hardware  models. Only one
3127              watchdog can be enabled for a guest.
3128
3129              The following models may be available:
3130
3131              ib700  iBASE 700 is a very simple ISA  watchdog  with  a  single
3132                     timer.
3133
3134              i6300esb
3135                     Intel  6300ESB I/O controller hub is a much more feature‐
3136                     ful PCI-based dual-timer watchdog.
3137
3138              diag288
3139                     A virtual watchdog for s390x backed by the  diagnose  288
3140                     hypercall (currently KVM only).
3141
3142       -watchdog-action action
3143              The  action  controls  what QEMU will do when the watchdog timer
3144              expires. The default is  reset  (forcefully  reset  the  guest).
3145              Other  possible  actions  are:  shutdown  (attempt to gracefully
3146              shutdown the guest), poweroff (forcefully poweroff  the  guest),
3147              inject-nmi  (inject  a  NMI  into  the  guest), pause (pause the
3148              guest), debug (print a debug message and continue), or none  (do
3149              nothing).
3150
3151              Note  that  the shutdown action requires that the guest responds
3152              to ACPI signals, which it may not be able to do in the  sort  of
3153              situations  where  the  watchdog  would  have  expired, and thus
3154              -watchdog-action shutdown is not recommended for production use.
3155
3156              Examples:
3157
3158              -watchdog i6300esb -watchdog-action pause; -watchdog ib700
3159
3160       -echr numeric_ascii_value
3161              Change the escape character used for switching  to  the  monitor
3162              when  using monitor and serial sharing. The default is 0x01 when
3163              using the -nographic option. 0x01  is  equal  to  pressing  Con‐
3164              trol-a. You can select a different character from the ascii con‐
3165              trol keys where 1 through 26 map to Control-a through Control-z.
3166              For instance you could use the either of the following to change
3167              the escape character to Control-t.
3168
3169              -echr 0x14; -echr 20
3170
3171       -show-cursor
3172              Show cursor.
3173
3174       -tb-size n
3175              Set TCG translation block cache size.  Deprecated,  use  '-accel
3176              tcg,tb-size=n' instead.
3177
3178       -incoming tcp:[host]:port[,to=maxport][,ipv4][,ipv6]
3179
3180
3181       -incoming rdma:host:port[,ipv4][,ipv6]
3182              Prepare for incoming migration, listen on a given tcp port.
3183
3184       -incoming unix:socketpath
3185              Prepare for incoming migration, listen on a given unix socket.
3186
3187       -incoming fd:fd
3188              Accept incoming migration from a given filedescriptor.
3189
3190       -incoming exec:cmdline
3191              Accept  incoming  migration as an output from specified external
3192              command.
3193
3194       -incoming defer
3195              Wait for the URI to be specified via migrate_incoming. The moni‐
3196              tor  can  be  used to change settings (such as migration parame‐
3197              ters) prior to issuing the migrate_incoming to allow the  migra‐
3198              tion to begin.
3199
3200       -only-migratable
3201              Only  allow  migratable  devices. Devices will not be allowed to
3202              enter an unmigratable state.
3203
3204       -nodefaults
3205              Don't create default devices. Normally, QEMU  sets  the  default
3206              devices  like serial port, parallel port, virtual console, moni‐
3207              tor device, VGA adapter, floppy and CD-ROM drive and others. The
3208              -nodefaults option will disable all those default devices.
3209
3210       -chroot dir
3211              Immediately before starting guest execution, chroot to the spec‐
3212              ified directory. Especially useful in combination with -runas.
3213
3214       -runas user
3215              Immediately before starting guest execution,  drop  root  privi‐
3216              leges, switching to the specified user.
3217
3218       -prom-env variable=value
3219              Set OpenBIOS nvram variable to given value (PPC, SPARC only).
3220
3221                 qemu-system-sparc -prom-env 'auto-boot?=false' \
3222                  -prom-env 'boot-device=sd(0,2,0):d' -prom-env 'boot-args=linux single'
3223
3224                 qemu-system-ppc -prom-env 'auto-boot?=false' \
3225                  -prom-env 'boot-device=hd:2,\yaboot' \
3226                  -prom-env 'boot-args=conf=hd:2,\yaboot.conf'
3227
3228       -semihosting
3229              Enable semihosting mode (ARM, M68K, Xtensa, MIPS, Nios II only).
3230
3231              Note  that  this allows guest direct access to the host filesys‐
3232              tem, so should only be used with a trusted guest OS.
3233
3234              See the -semihosting-config  option  documentation  for  further
3235              information about the facilities this enables.
3236
3237       -semihosting-config                               [enable=on|off][,tar‐
3238       get=native|gdb|auto][,chardev=id][,arg=str[,...]]
3239              Enable and configure semihosting (ARM, M68K, Xtensa, MIPS,  Nios
3240              II only).
3241
3242              Note  that  this allows guest direct access to the host filesys‐
3243              tem, so should only be used with a trusted guest OS.
3244
3245              On Arm this implements the  standard  semihosting  API,  version
3246              2.0.
3247
3248              On  M68K  this  implements  the "ColdFire GDB" interface used by
3249              libgloss.
3250
3251              Xtensa  semihosting  provides  basic  file  IO  calls,  such  as
3252              open/read/write/seek/select.  Tensilica  baremetal  libc for ISS
3253              and linux platform "sim" use this interface.
3254
3255              target=native|gdb|auto
3256                     Defines where the semihosting calls will be addressed, to
3257                     QEMU (native) or to GDB (gdb). The default is auto, which
3258                     means gdb during debug sessions and native otherwise.
3259
3260              chardev=str1
3261                     Send the output to a chardev backend output for native or
3262                     auto output when not in gdb
3263
3264              arg=str1,arg=str2,...
3265                     Allows  the user to pass input arguments, and can be used
3266                     multiple times to build up a list.  The  old-style  -ker‐
3267                     nel/-append  method  of  passing  a command line is still
3268                     supported for backward compatibility. If both the --semi‐
3269                     hosting-config arg and the -kernel/-append are specified,
3270                     the former is passed to semihosting as  it  always  takes
3271                     precedence.
3272
3273       -old-param
3274              Old param mode (ARM only).
3275
3276       -sandbox                           arg[,obsolete=string][,elevateprivi‐
3277       leges=string][,spawn=string][,resourcecontrol=string]
3278              Enable Seccomp mode 2  system  call  filter.  'on'  will  enable
3279              syscall  filtering  and  'off'  will  disable it. The default is
3280              'off'.
3281
3282              obsolete=string
3283                     Enable Obsolete system calls
3284
3285              elevateprivileges=string
3286                     Disable set*uid|gid system calls
3287
3288              spawn=string
3289                     Disable *fork and execve
3290
3291              resourcecontrol=string
3292                     Disable process affinity and schedular priority
3293
3294       -readconfig file
3295              Read device configuration from file.  This  approach  is  useful
3296              when  you  want  to  spawn  QEMU  process with many command line
3297              options but you don't want to exceed the command line  character
3298              limit.
3299
3300       -writeconfig file
3301              Write device configuration to file. The file can be either file‐
3302              name to save command line and device configuration into file  or
3303              dash  -)  character  to  print the output to stdout. This can be
3304              later used as input file for -readconfig option.
3305
3306       -no-user-config
3307              The -no-user-config option  makes  QEMU  not  load  any  of  the
3308              user-provided config files on sysconfdir.
3309
3310       -trace [[enable=]pattern][,events=file][,file=file]
3311              Specify tracing options.
3312
3313              [enable=]PATTERN
3314                     Immediately  enable events matching PATTERN (either event
3315                     name or a globbing pattern).  This option is only  avail‐
3316                     able  if  QEMU  has been compiled with the simple, log or
3317                     ftrace tracing backend.  To specify  multiple  events  or
3318                     patterns, specify the -trace option multiple times.
3319
3320                     Use -trace help to print a list of names of trace points.
3321
3322              events=FILE
3323                     Immediately  enable events listed in FILE.  The file must
3324                     contain one event name (as listed in the trace-events-all
3325                     file) per line; globbing patterns are accepted too.  This
3326                     option is only available if QEMU has been  compiled  with
3327                     the simple, log or ftrace tracing backend.
3328
3329              file=FILE
3330                     Log output traces to FILE.  This option is only available
3331                     if QEMU has been compiled with the simple  tracing  back‐
3332                     end.
3333
3334       -plugin file=file[,arg=string]
3335              Load a plugin.
3336
3337              file=file
3338                     Load the given plugin from a shared library file.
3339
3340              arg=string
3341                     Argument  string passed to the plugin. (Can be given mul‐
3342                     tiple times.)
3343
3344       -enable-fips
3345              Enable FIPS 140-2 compliance mode.
3346
3347       -msg [timestamp[=on|off]][,guest-name[=on|off]]
3348              Control error message format.
3349
3350              timestamp=on|off
3351                     Prefix messages with a timestamp. Default is off.
3352
3353              guest-name=on|off
3354                     Prefix messages with guest name but only if  -name  guest
3355                     option is set otherwise the option is ignored. Default is
3356                     off.
3357
3358       -dump-vmstate file
3359              Dump json-encoded vmstate information for current  machine  type
3360              to file in file
3361
3362       -enable-sync-profile
3363              Enable synchronization profiling.
3364
3365   Generic object creation
3366       -object typename[,prop1=value1,...]
3367              Create  a  new object of type typename setting properties in the
3368              order they are specified. Note that the 'id'  property  must  be
3369              set. These objects are placed in the '/objects' path.
3370
3371              -object                                             memory-back‐
3372              end-file,id=id,size=size,mem-path=dir,share=on|off,dis‐
3373              card-data=on|off,merge=on|off,dump=on|off,preal‐
3374              loc=on|off,host-nodes=host-nodes,policy=default|pre‐
3375              ferred|bind|interleave,align=align
3376                     Creates  a  memory file backend object, which can be used
3377                     to back the guest RAM with huge pages.
3378
3379                     The id parameter is a unique ID that will be used to ref‐
3380                     erence  this  memory  region  when  configuring the -numa
3381                     argument.
3382
3383                     The size option provides the size of the  memory  region,
3384                     and accepts common suffixes, eg 500M.
3385
3386                     The  mem-path provides the path to either a shared memory
3387                     or huge page filesystem mount.
3388
3389                     The share boolean option determines  whether  the  memory
3390                     region  is marked as private to QEMU, or shared. The lat‐
3391                     ter allows a co-operating external process to access  the
3392                     QEMU memory region.
3393
3394                     The share is also required for pvrdma devices due to lim‐
3395                     itations in the RDMA API provided by Linux.
3396
3397                     Setting share=on might affect the  ability  to  configure
3398                     NUMA  bindings  for the memory backend under some circum‐
3399                     stances, see  Documentation/vm/numa_memory_policy.txt  on
3400                     the Linux kernel source tree for additional details.
3401
3402                     Setting  the  discard-data boolean option to on indicates
3403                     that file contents can be destroyed when QEMU  exits,  to
3404                     avoid  unnecessarily  flushing  data to the backing file.
3405                     Note that discard-data is only an optimization, and  QEMU
3406                     might not discard file contents if it aborts unexpectedly
3407                     or is terminated using SIGKILL.
3408
3409                     The merge boolean option enables memory merge, also known
3410                     as  MADV_MERGEABLE,  so that Kernel Samepage Merging will
3411                     consider the pages for memory deduplication.
3412
3413                     Setting the dump boolean option to off excludes the  mem‐
3414                     ory  from  core  dumps.  This  feature  is  also known as
3415                     MADV_DONTDUMP.
3416
3417                     The prealloc boolean option enables memory preallocation.
3418
3419                     The host-nodes option binds the memory range to a list of
3420                     NUMA host nodes.
3421
3422                     The policy option sets the NUMA policy to one of the fol‐
3423                     lowing values:
3424
3425                     default
3426                            default host policy
3427
3428                     preferred
3429                            prefer the given host node list for allocation
3430
3431                     bind   restrict memory allocation to the given host  node
3432                            list
3433
3434                     interleave
3435                            interleave  memory  allocations  across  the given
3436                            host node list
3437
3438                     The align option specifies  the  base  address  alignment
3439                     when  QEMU mmap(2) mem-path, and accepts common suffixes,
3440                     eg 2M. Some backend store specified by mem-path  requires
3441                     an alignment different than the default one used by QEMU,
3442                     eg the  device  DAX  /dev/dax0.0  requires  2M  alignment
3443                     rather  than  4K.  In  such  cases, users can specify the
3444                     required alignment via this option.
3445
3446                     The pmem option specifies whether the backing file speci‐
3447                     fied by mem-path is in host persistent memory that can be
3448                     accessed using the SNIA NVM programming model (e.g. Intel
3449                     NVDIMM). If pmem is set to 'on', QEMU will take necessary
3450                     operations to guarantee the persistence of its own writes
3451                     to  mem-path  (e.g.  in  vNVDIMM label emulation and live
3452                     migration). Also,  we  will  map  the  backend-file  with
3453                     MAP_SYNC flag, which ensures the file metadata is in sync
3454                     for mem-path in case of host crash or  a  power  failure.
3455                     MAP_SYNC  requires  support  from  both  the  host kernel
3456                     (since Linux kernel 4.15) and the filesystem of  mem-path
3457                     mounted with DAX option.
3458
3459              -object                                             memory-back‐
3460              end-ram,id=id,merge=on|off,dump=on|off,share=on|off,preal‐
3461              loc=on|off,size=size,host-nodes=host-nodes,policy=default|pre‐
3462              ferred|bind|interleave
3463                     Creates a memory backend object, which  can  be  used  to
3464                     back  the  guest  RAM.  Memory backend objects offer more
3465                     control than the -m option that is traditionally used  to
3466                     define  guest  RAM.   Please refer to memory-backend-file
3467                     for a description of the options.
3468
3469              -object                                             memory-back‐
3470              end-memfd,id=id,merge=on|off,dump=on|off,share=on|off,preal‐
3471              loc=on|off,size=size,host-nodes=host-nodes,policy=default|pre‐
3472              ferred|bind|interleave,seal=on|off,hugetlb=on|off,hugetlb‐
3473              size=size
3474                     Creates an anonymous memory file  backend  object,  which
3475                     allows  QEMU to share the memory with an external process
3476                     (e.g. when using vhost-user).  The  memory  is  allocated
3477                     with memfd and optional sealing. (Linux only)
3478
3479                     The  seal  option  creates a sealed-file, that will block
3480                     further resizing the memory ('on' by default).
3481
3482                     The hugetlb option specify the file to be created resides
3483                     in  the  hugetlbfs filesystem (since Linux 4.14). Used in
3484                     conjunction with  the  hugetlb  option,  the  hugetlbsize
3485                     option specify the hugetlb page size on systems that sup‐
3486                     port multiple hugetlb page sizes (it must be a power of 2
3487                     value supported by the system).
3488
3489                     In  some  versions of Linux, the hugetlb option is incom‐
3490                     patible with the seal option  (requires  at  least  Linux
3491                     4.16).
3492
3493                     Please  refer to memory-backend-file for a description of
3494                     the other options.
3495
3496                     The share boolean option is on by default with memfd.
3497
3498              -object rng-builtin,id=id
3499                     Creates a random number generator backend  which  obtains
3500                     entropy  from QEMU builtin functions. The id parameter is
3501                     a unique ID that will be used to reference  this  entropy
3502                     backend  from the virtio-rng device. By default, the vir‐
3503                     tio-rng device uses this RNG backend.
3504
3505              -object rng-random,id=id,filename=/dev/random
3506                     Creates a random number generator backend  which  obtains
3507                     entropy  from a device on the host. The id parameter is a
3508                     unique ID that will be used  to  reference  this  entropy
3509                     backend  from the virtio-rng device. The filename parame‐
3510                     ter specifies which file to obtain entropy  from  and  if
3511                     omitted defaults to /dev/urandom.
3512
3513              -object rng-egd,id=id,chardev=chardevid
3514                     Creates  a  random number generator backend which obtains
3515                     entropy from an external daemon running on the host.  The
3516                     id  parameter  is a unique ID that will be used to refer‐
3517                     ence this entropy backend from the virtio-rng device. The
3518                     chardev  parameter is the unique ID of a character device
3519                     backend that provides the connection to the RNG daemon.
3520
3521              -object                       tls-creds-anon,id=id,endpoint=end‐
3522              point,dir=/path/to/cred/dir,verify-peer=on|off
3523                     Creates  a TLS anonymous credentials object, which can be
3524                     used to provide TLS support on network backends.  The  id
3525                     parameter  is a unique ID which network backends will use
3526                     to access the credentials. The endpoint is either  server
3527                     or  client  depending on whether the QEMU network backend
3528                     that uses the credentials will be acting as a  client  or
3529                     as a server. If verify-peer is enabled (the default) then
3530                     once the handshake is  completed,  the  peer  credentials
3531                     will  be  verified,  though this is a no-op for anonymous
3532                     credentials.
3533
3534                     The dir parameter tells QEMU where to find the credential
3535                     files.   For server endpoints, this directory may contain
3536                     a file dh-params.pem providing diffie-hellman  parameters
3537                     to  use  for the TLS server. If the file is missing, QEMU
3538                     will generate a set of DH parameters at startup. This  is
3539                     a  computationally expensive operation that consumes ran‐
3540                     dom pool entropy, so it is recommended that a  persistent
3541                     set of parameters be generated upfront and saved.
3542
3543              -object                        tls-creds-psk,id=id,endpoint=end‐
3544              point,dir=/path/to/keys/dir[,username=username]
3545                     Creates a TLS Pre-Shared Keys (PSK)  credentials  object,
3546                     which can be used to provide TLS support on network back‐
3547                     ends. The id parameter is a unique ID which network back‐
3548                     ends  will use to access the credentials. The endpoint is
3549                     either server or client depending  on  whether  the  QEMU
3550                     network  backend that uses the credentials will be acting
3551                     as a client or as a server.  For clients  only,  username
3552                     is  the  username  which  will  be sent to the server. If
3553                     omitted it defaults to "qemu".
3554
3555                     The dir parameter tells QEMU where to find the keys file.
3556                     It  is  called "dir/keys.psk" and contains "username:key"
3557                     pairs. This file can most easily  be  created  using  the
3558                     GnuTLS psktool program.
3559
3560                     For  server  endpoints,  dir  may  also  contain  a  file
3561                     dh-params.pem providing diffie-hellman parameters to  use
3562                     for  the  TLS  server.  If the file is missing, QEMU will
3563                     generate a set of DH parameters at  startup.  This  is  a
3564                     computationally  expensive operation that consumes random
3565                     pool entropy, so it is recommended that a persistent  set
3566                     of parameters be generated up front and saved.
3567
3568              -object                       tls-creds-x509,id=id,endpoint=end‐
3569              point,dir=/path/to/cred/dir,priority=priority,ver‐
3570              ify-peer=on|off,passwordid=id
3571                     Creates  a TLS anonymous credentials object, which can be
3572                     used to provide TLS support on network backends.  The  id
3573                     parameter  is a unique ID which network backends will use
3574                     to access the credentials. The endpoint is either  server
3575                     or  client  depending on whether the QEMU network backend
3576                     that uses the credentials will be acting as a  client  or
3577                     as a server. If verify-peer is enabled (the default) then
3578                     once the handshake is  completed,  the  peer  credentials
3579                     will  be  verified.  With x509 certificates, this implies
3580                     that the clients must be provided with valid client  cer‐
3581                     tificates too.
3582
3583                     The dir parameter tells QEMU where to find the credential
3584                     files.  For server endpoints, this directory may  contain
3585                     a  file dh-params.pem providing diffie-hellman parameters
3586                     to use for the TLS server. If the file is  missing,  QEMU
3587                     will  generate a set of DH parameters at startup. This is
3588                     a computationally expensive operation that consumes  ran‐
3589                     dom  pool entropy, so it is recommended that a persistent
3590                     set of parameters be generated upfront and saved.
3591
3592                     For x509 certificate credentials the directory will  con‐
3593                     tain  further  files providing the x509 certificates. The
3594                     certificates must be stored in PEM format,  in  filenames
3595                     ca-cert.pem, ca-crl.pem (optional), server-cert.pem (only
3596                     servers), server-key.pem (only servers),  client-cert.pem
3597                     (only clients), and client-key.pem (only clients).
3598
3599                     For  the  server-key.pem  and  client-key.pem files which
3600                     contain sensitive private keys, it is possible to use  an
3601                     encrypted  version by providing the passwordid parameter.
3602                     This provides the  ID  of  a  previously  created  secret
3603                     object containing the password for decryption.
3604
3605                     The  priority  parameter  allows  to  override the global
3606                     default priority used by gnutls. This can  be  useful  if
3607                     the  system  administrator  needs  to use a weaker set of
3608                     crypto priorities for QEMU  without  potentially  forcing
3609                     the  weakness onto all applications. Or conversely if one
3610                     wants wants a stronger default  for  QEMU  than  for  all
3611                     other applications, they can do this through this parame‐
3612                     ter. Its format is a gnutls priority string as  described
3613                     at
3614                     https://gnutls.org/manual/html_node/Priority-Strings.html.
3615
3616              -object tls-cipher-suites,id=id,priority=priority
3617                     Creates  a TLS cipher suites object, which can be used to
3618                     control the TLS cipher/protocol algorithms that  applica‐
3619                     tions are permitted to use.
3620
3621                     The  id parameter is a unique ID which frontends will use
3622                     to access the ordered list of permitted TLS cipher suites
3623                     from the host.
3624
3625                     The  priority  parameter  allows  to  override the global
3626                     default priority used by gnutls. This can  be  useful  if
3627                     the  system  administrator  needs  to use a weaker set of
3628                     crypto priorities for QEMU  without  potentially  forcing
3629                     the  weakness onto all applications. Or conversely if one
3630                     wants wants a stronger default  for  QEMU  than  for  all
3631                     other applications, they can do this through this parame‐
3632                     ter. Its format is a gnutls priority string as  described
3633                     at
3634                     https://gnutls.org/manual/html_node/Priority-Strings.html.
3635
3636                     An example of use of this object is to control UEFI HTTPS
3637                     Boot.  The tls-cipher-suites object exposes  the  ordered
3638                     list of permitted TLS cipher suites from the host side to
3639                     the guest firmware, via fw_cfg. The list  is  represented
3640                     as an array of IANA_TLS_CIPHER objects. The firmware uses
3641                     the IANA_TLS_CIPHER array for configuring guest-side TLS.
3642
3643                     In the following  example,  the  priority  at  which  the
3644                     host-side  policy  is  retrieved is given by the priority
3645                     property.  Given that QEMU uses GNUTLS,  priority=@SYSTEM
3646                     may    be    used    to    refer   to   /etc/crypto-poli‐
3647                     cies/back-ends/gnutls.config.
3648
3649                        # qemu-system-x86_64     -object tls-cipher-suites,id=mysuite0,priority=@SYSTEM     -fw_cfg name=etc/edk2/https/ciphers,gen_id=mysuite0
3650
3651              -object               filter-buffer,id=id,netdev=netdevid,inter‐
3652              val=t[,queue=all|rx|tx][,status=on|off][,posi‐
3653              tion=head|tail|id=<id>][,insert=behind|before]
3654                     Interval t can't be 0, this  filter  batches  the  packet
3655                     delivery:  all  packets  arriving  in a given interval on
3656                     netdev netdevid are delayed until the end of  the  inter‐
3657                     val. Interval is in microseconds. status is optional that
3658                     indicate whether the netfilter is  on  (enabled)  or  off
3659                     (disabled),  the  default  status  for  netfilter will be
3660                     'on'.
3661
3662                     queue all|rx|tx is an option that can be applied  to  any
3663                     netfilter.
3664
3665                     all:  the  filter is attached both to the receive and the
3666                     transmit queue of the netdev (default).
3667
3668                     rx: the filter is attached to the receive  queue  of  the
3669                     netdev, where it will receive packets sent to the netdev.
3670
3671                     tx:  the  filter is attached to the transmit queue of the
3672                     netdev, where it will receive packets sent by the netdev.
3673
3674                     position head|tail|id=<id> is an option to specify  where
3675                     the  filter should be inserted in the filter list. It can
3676                     be applied to any netfilter.
3677
3678                     head: the filter is inserted at the head  of  the  filter
3679                     list, before any existing filters.
3680
3681                     tail:  the  filter  is inserted at the tail of the filter
3682                     list, behind any existing filters (default).
3683
3684                     id=<id>: the filter is inserted before or behind the fil‐
3685                     ter specified by <id>, see the insert option below.
3686
3687                     insert  behind|before  is  an  option to specify where to
3688                     insert the new filter relative to the one specified  with
3689                     position=id=<id>. It can be applied to any netfilter.
3690
3691                     before: insert before the specified filter.
3692
3693                     behind: insert behind the specified filter (default).
3694
3695              -object       filter-mirror,id=id,netdev=netdevid,outdev=charde‐
3696              vid,queue=all|rx|tx[,vnet_hdr_support][,posi‐
3697              tion=head|tail|id=<id>][,insert=behind|before]
3698                     filter-mirror  on  netdev  netdevid,mirror  net packet to
3699                     chardevchardevid, if it has  the  vnet_hdr_support  flag,
3700                     filter-mirror will mirror packet with vnet_hdr_len.
3701
3702              -object    filter-redirector,id=id,netdev=netdevid,indev=charde‐
3703              vid,outdev=chardevid,queue=all|rx|tx[,vnet_hdr_support][,posi‐
3704              tion=head|tail|id=<id>][,insert=behind|before]
3705                     filter-redirector  on  netdev  netdevid,redirect filter's
3706                     net packet  to  chardev  chardevid,and  redirect  indev's
3707                     packet  to  filter.if  it  has the vnet_hdr_support flag,
3708                     filter-redirector will redirect packet with vnet_hdr_len.
3709                     Create  a  filter-redirector  we need to differ outdev id
3710                     from indev id, id can not be the same. we  can  just  use
3711                     indev or outdev, but at least one of indev or outdev need
3712                     to be specified.
3713
3714              -object                      filter-rewriter,id=id,netdev=netde‐
3715              vid,queue=all|rx|tx,[vnet_hdr_support][,posi‐
3716              tion=head|tail|id=<id>][,insert=behind|before]
3717                     Filter-rewriter is a part of COLO project.It will rewrite
3718                     tcp  packet  to  secondary from primary to keep secondary
3719                     tcp connection,and rewrite tcp  packet  to  primary  from
3720                     secondary  make tcp packet can be handled by client.if it
3721                     has the vnet_hdr_support flag, we can parse  packet  with
3722                     vnet header.
3723
3724                     usage:    colo    secondary:    -object   filter-redirec‐
3725                     tor,id=f1,netdev=hn0,queue=tx,indev=red0   -object   fil‐
3726                     ter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1
3727                     -object filter-rewriter,id=rew0,netdev=hn0,queue=all
3728
3729              -object                 filter-dump,id=id,netdev=dev[,file=file‐
3730              name][,maxlen=len][,posi‐
3731              tion=head|tail|id=<id>][,insert=behind|before]
3732                     Dump the network traffic on netdev dev to the file speci‐
3733                     fied  by filename. At most len bytes (64k by default) per
3734                     packet are stored. The file format is libpcap, so it  can
3735                     be analyzed with tools such as tcpdump or Wireshark.
3736
3737              -object             colo-compare,id=id,primary_in=chardevid,sec‐
3738              ondary_in=chardevid,outdev=chardevid,iothread=id[,vnet_hdr_sup‐
3739              port][,notify_dev=id][,compare_time‐
3740              out=@var{ms}][,expired_scan_cycle=@var{ms}][,max_queue_size=@var{size}]
3741                     Colo-compare  gets  packet  from primary_in chardevid and
3742                     secondary_in, then compare whether the payload of primary
3743                     packet  and  secondary  packet  are the same. If same, it
3744                     will output primary  packet  to  out_dev,  else  it  will
3745                     notify  COLO-framework  to do checkpoint and send primary
3746                     packet to out_dev. In order  to  improve  efficiency,  we
3747                     need  to  put the task of comparison in another iothread.
3748                     If it has the vnet_hdr_support flag,  colo  compare  will
3749                     send/recv      packet     with     vnet_hdr_len.      The
3750                     compare_timeout=@var{ms} determines the maximum  time  of
3751                     the     colo-compare     hold     the     packet.     The
3752                     expired_scan_cycle=@var{ms} is to set the period of scan‐
3753                     ning   expired   primary   node   network  packets.   The
3754                     max_queue_size=@var{size} is to set the max compare queue
3755                     size depend on user environment.  If user want to use Xen
3756                     COLO, need to add the notify_dev to notify Xen colo-frame
3757                     to do checkpoint.
3758
3759                     COLO-compare must be used with the help of filter-mirror,
3760                     filter-redirector and filter-rewriter.
3761
3762                        KVM COLO
3763
3764                        primary:
3765                        -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown
3766                        -device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66
3767                        -chardev socket,id=mirror0,host=3.3.3.3,port=9003,server,nowait
3768                        -chardev socket,id=compare1,host=3.3.3.3,port=9004,server,nowait
3769                        -chardev socket,id=compare0,host=3.3.3.3,port=9001,server,nowait
3770                        -chardev socket,id=compare0-0,host=3.3.3.3,port=9001
3771                        -chardev socket,id=compare_out,host=3.3.3.3,port=9005,server,nowait
3772                        -chardev socket,id=compare_out0,host=3.3.3.3,port=9005
3773                        -object iothread,id=iothread1
3774                        -object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0
3775                        -object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out
3776                        -object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0
3777                        -object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0,iothread=iothread1
3778
3779                        secondary:
3780                        -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown
3781                        -device e1000,netdev=hn0,mac=52:a4:00:12:78:66
3782                        -chardev socket,id=red0,host=3.3.3.3,port=9003
3783                        -chardev socket,id=red1,host=3.3.3.3,port=9004
3784                        -object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0
3785                        -object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1
3786
3787
3788                        Xen COLO
3789
3790                        primary:
3791                        -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown
3792                        -device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66
3793                        -chardev socket,id=mirror0,host=3.3.3.3,port=9003,server,nowait
3794                        -chardev socket,id=compare1,host=3.3.3.3,port=9004,server,nowait
3795                        -chardev socket,id=compare0,host=3.3.3.3,port=9001,server,nowait
3796                        -chardev socket,id=compare0-0,host=3.3.3.3,port=9001
3797                        -chardev socket,id=compare_out,host=3.3.3.3,port=9005,server,nowait
3798                        -chardev socket,id=compare_out0,host=3.3.3.3,port=9005
3799                        -chardev socket,id=notify_way,host=3.3.3.3,port=9009,server,nowait
3800                        -object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0
3801                        -object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out
3802                        -object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0
3803                        -object iothread,id=iothread1
3804                        -object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0,notify_dev=nofity_way,iothread=iothread1
3805
3806                        secondary:
3807                        -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown
3808                        -device e1000,netdev=hn0,mac=52:a4:00:12:78:66
3809                        -chardev socket,id=red0,host=3.3.3.3,port=9003
3810                        -chardev socket,id=red1,host=3.3.3.3,port=9004
3811                        -object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0
3812                        -object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1
3813
3814                     If you want to know the detail of above command line, you
3815                     can read the colo-compare git log.
3816
3817              -object cryptodev-backend-builtin,id=id[,queues=queues]
3818                     Creates   a   cryptodev  backend  which  executes  crypto
3819                     opreation from the QEMU cipher APIS. The id parameter  is
3820                     a unique ID that will be used to reference this cryptodev
3821                     backend from the virtio-crypto device. The queues parame‐
3822                     ter  is optional, which specify the queue number of cryp‐
3823                     todev backend, the default of queues is 1.
3824
3825                        # qemu-system-x86_64   [...]       -object cryptodev-backend-builtin,id=cryptodev0       -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0   [...]
3826
3827              -object               cryptodev-vhost-user,id=id,chardev=charde‐
3828              vid[,queues=queues]
3829                     Creates  a  vhost-user  cryptodev  backend,  backed  by a
3830                     chardev chardevid. The id parameter is a unique  ID  that
3831                     will be used to reference this cryptodev backend from the
3832                     virtio-crypto device. The chardev should be a unix domain
3833                     socket  backed  one.   The vhost-user uses a specifically
3834                     defined protocol to pass vhost ioctl replacement messages
3835                     to  an  application  on  the other end of the socket. The
3836                     queues parameter is optional,  which  specify  the  queue
3837                     number  of  cryptodev  backend for multiqueue vhost-user,
3838                     the default of queues is 1.
3839
3840                        # qemu-system-x86_64   [...]       -chardev socket,id=chardev0,path=/path/to/socket       -object cryptodev-vhost-user,id=cryptodev0,chardev=chardev0       -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0   [...]
3841
3842              -object                            secret,id=id,data=string,for‐
3843              mat=raw|base64[,keyid=secretid,iv=string]
3844
3845
3846              -object                          secret,id=id,file=filename,for‐
3847              mat=raw|base64[,keyid=secretid,iv=string]
3848                     Defines a secret to store a password, encryption key,  or
3849                     some  other sensitive data. The sensitive data can either
3850                     be passed directly via the data parameter, or  indirectly
3851                     via the file parameter. Using the data parameter is inse‐
3852                     cure unless the sensitive data is encrypted.
3853
3854                     The sensitive data can be provided  in  raw  format  (the
3855                     default), or base64. When encoded as JSON, the raw format
3856                     only supports valid UTF-8 characters, so base64 is recom‐
3857                     mended  for  sending  binary data. QEMU will convert from
3858                     which ever format is provided  to  the  format  it  needs
3859                     internally.  eg,  an  RBD password can be provided in raw
3860                     format, even though it will be base64 encoded when passed
3861                     onto the RBD sever.
3862
3863                     For  added protection, it is possible to encrypt the data
3864                     associated with a secret using  the  AES-256-CBC  cipher.
3865                     Use of encryption is indicated by providing the keyid and
3866                     iv parameters. The keyid parameter provides the ID  of  a
3867                     previously  defined  secret  that  contains  the  AES-256
3868                     decryption key. This key should be 32-bytes long  and  be
3869                     base64 encoded. The iv parameter provides the random ini‐
3870                     tialization vector used for encryption of this particular
3871                     secret  and  should  be  a base64 encrypted string of the
3872                     16-byte IV.
3873
3874                     The simplest (insecure) usage is to  provide  the  secret
3875                     inline
3876
3877                        # qemu-system-x86_64 -object secret,id=sec0,data=letmein,format=raw
3878
3879                     The  simplest secure usage is to provide the secret via a
3880                     file
3881
3882                     # printf "letmein"  >  mypasswd.txt  #  QEMU_SYSTEM_MACRO
3883                     -object secret,id=sec0,file=mypasswd.txt,format=raw
3884
3885                     For  greater  security,  AES-256-CBC  should  be used. To
3886                     illustrate usage, consider the openssl command line  tool
3887                     which  can  encrypt  the data. Note that when encrypting,
3888                     the plaintext must be padded to the cipher block size (32
3889                     bytes)  using  the  standard  PKCS#5/6 compatible padding
3890                     algorithm.
3891
3892                     First a master key needs to be created in  base64  encod‐
3893                     ing:
3894
3895                        # openssl rand -base64 32 > key.b64
3896                        # KEY=$(base64 -d key.b64 | hexdump  -v -e '/1 "%02X"')
3897
3898                     Each  secret  to be encrypted needs to have a random ini‐
3899                     tialization vector generated. These do  not  need  to  be
3900                     kept secret
3901
3902                        # openssl rand -base64 16 > iv.b64
3903                        # IV=$(base64 -d iv.b64 | hexdump  -v -e '/1 "%02X"')
3904
3905                     The  secret  to  be defined can now be encrypted, in this
3906                     case we're telling openssl to base64 encode  the  result,
3907                     but it could be left as raw bytes if desired.
3908
3909                        # SECRET=$(printf "letmein" |
3910                                   openssl enc -aes-256-cbc -a -K $KEY -iv $IV)
3911
3912                     When  launching  QEMU, create a master secret pointing to
3913                     key.b64 and specify that to be used to decrypt  the  user
3914                     password.  Pass  the  contents  of  iv.b64  to the second
3915                     secret
3916
3917                        # qemu-system-x86_64     -object secret,id=secmaster0,format=base64,file=key.b64     -object secret,id=sec0,keyid=secmaster0,format=base64,        data=$SECRET,iv=$(<iv.b64)
3918
3919              -object                            sev-guest,id=id,cbitpos=cbit‐
3920              pos,reduced-phys-bits=val,[sev-device=string,policy=policy,han‐
3921              dle=handle,dh-cert-file=file,session-file=file]
3922                     Create a  Secure  Encrypted  Virtualization  (SEV)  guest
3923                     object,  which  can  be  used to provide the guest memory
3924                     encryption support on AMD processors.
3925
3926                     When memory encryption is enabled, one  of  the  physical
3927                     address bit (aka the C-bit) is utilized to mark if a mem‐
3928                     ory page is protected. The cbitpos is used to provide the
3929                     C-bit  position. The C-bit position is Host family depen‐
3930                     dent hence user must provide this  value.  On  EPYC,  the
3931                     value should be 47.
3932
3933                     When  memory encryption is enabled, we loose certain bits
3934                     in physical address space. The reduced-phys-bits is  used
3935                     to  provide  the  number  of  bits  we  loose in physical
3936                     address space.  Similar to C-bit, the value is Host  fam‐
3937                     ily dependent. On EPYC, the value should be 5.
3938
3939                     The sev-device provides the device file to use for commu‐
3940                     nicating with the SEV firmware running inside AMD  Secure
3941                     Processor.  The default device is '/dev/sev'. If hardware
3942                     supports memory encryption then /dev/sev devices are cre‐
3943                     ated by CCP driver.
3944
3945                     The  policy  provides  the guest policy to be enforced by
3946                     the SEV firmware  and  restrict  what  configuration  and
3947                     operational  commands  can  be performed on this guest by
3948                     the hypervisor. The policy  should  be  provided  by  the
3949                     guest  owner  and  is  bound  to  the guest and cannot be
3950                     changed throughout the lifetime of the guest. The default
3951                     is 0.
3952
3953                     If  guest  policy allows sharing the key with another SEV
3954                     guest then handle can be use to  provide  handle  of  the
3955                     guest from which to share the key.
3956
3957                     The  dh-cert-file  and  session-file  provides  the guest
3958                     owner's Public Diffie-Hillman key defined  in  SEV  spec.
3959                     The  PDH and session parameters are used for establishing
3960                     a cryptographic session with the guest owner to negotiate
3961                     keys  used  for  attestation. The file must be encoded in
3962                     base64.
3963
3964                     e.g to launch a SEV guest
3965
3966                        # qemu_system-x86_64     ......
3967                            -object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=5     -machine ...,memory-encryption=sev0
3968                            .....
3969
3970              -object authz-simple,id=id,identity=string
3971                     Create an authorization object that will  control  access
3972                     to network services.
3973
3974                     The  identity  parameter  is  identifies the user and its
3975                     format depends on the network service that  authorization
3976                     object  is  associated with. For authorizing based on TLS
3977                     x509 certificates, the identity must be the x509  distin‐
3978                     guished  name. Note that care must be taken to escape any
3979                     commas in the distinguished name.
3980
3981                     An example authorization object to validate a  x509  dis‐
3982                     tinguished name would look like:
3983
3984                        # qemu-system-x86_64     ...
3985                            -object 'authz-simple,id=auth0,identity=CN=laptop.example.com,,O=Example Org,,L=London,,ST=London,,C=GB'     ...
3986
3987                     Note the use of quotes due to the x509 distinguished name
3988                     containing whitespace, and escaping of ','.
3989
3990              -object authz-listfile,id=id,filename=path,refresh=yes|no
3991                     Create an authorization object that will  control  access
3992                     to network services.
3993
3994                     The  filename  parameter is the fully qualified path to a
3995                     file containing the access control  list  rules  in  JSON
3996                     format.
3997
3998                     An example set of rules that match against SASL usernames
3999                     might look like:
4000
4001                        {
4002                          "rules": [
4003                             { "match": "fred", "policy": "allow", "format": "exact" },
4004                             { "match": "bob", "policy": "allow", "format": "exact" },
4005                             { "match": "danb", "policy": "deny", "format": "glob" },
4006                             { "match": "dan*", "policy": "allow", "format": "exact" },
4007                          ],
4008                          "policy": "deny"
4009                        }
4010
4011                     When checking access the object will iterate over all the
4012                     rules  and  the  first rule to match will have its policy
4013                     value returned as the result. If no rules match, then the
4014                     default policy value is returned.
4015
4016                     The  rules  can  either be an exact string match, or they
4017                     can use the simple UNIX glob pattern  matching  to  allow
4018                     wildcards to be used.
4019
4020                     If  refresh is set to true the file will be monitored and
4021                     automatically reloaded whenever its content changes.
4022
4023                     As with the authz-simple object, the format of the  iden‐
4024                     tity  strings  being  matched depends on the network ser‐
4025                     vice, but is usually a TLS x509 distinguished name, or  a
4026                     SASL username.
4027
4028                     An  example authorization object to validate a SASL user‐
4029                     name would look like:
4030
4031                        # qemu-system-x86_64     ...
4032                            -object authz-simple,id=auth0,filename=/etc/qemu/vnc-sasl.acl,refresh=yes
4033                            ...
4034
4035              -object authz-pam,id=id,service=string
4036                     Create an authorization object that will  control  access
4037                     to network services.
4038
4039                     The  service parameter provides the name of a PAM service
4040                     to  use  for  authorization.  It  requires  that  a  file
4041                     /etc/pam.d/service exist to provide the configuration for
4042                     the account subsystem.
4043
4044                     An example authorization object to validate  a  TLS  x509
4045                     distinguished name would look like:
4046
4047                        # qemu-system-x86_64     ...
4048                            -object authz-pam,id=auth0,service=qemu-vnc
4049                            ...
4050
4051                     There  would  then be a corresponding config file for PAM
4052                     at /etc/pam.d/qemu-vnc that contains:
4053
4054                        account requisite  pam_listfile.so item=user sense=allow \
4055                                   file=/etc/qemu/vnc.allow
4056
4057                     Finally the /etc/qemu/vnc.allow file  would  contain  the
4058                     list of x509 distingished names that are permitted access
4059
4060                        CN=laptop.example.com,O=Example Home,L=London,ST=London,C=GB
4061
4062              -object
4063              iothread,id=id,poll-max-ns=poll-max-ns,poll-grow=poll-grow,poll-shrink=poll-shrink
4064                     Creates a dedicated event loop thread that devices can be
4065                     assigned to. This is known as  an  IOThread.  By  default
4066                     device  emulation  happens  in  vCPU  threads or the main
4067                     event loop thread.  This can become a scalability bottle‐
4068                     neck.  IOThreads allow device emulation and I/O to run on
4069                     other host CPUs.
4070
4071                     The id parameter is a unique ID that will be used to ref‐
4072                     erence  this IOThread from -device ...,iothread=id.  Mul‐
4073                     tiple devices can be assigned to an IOThread.  Note  that
4074                     not all devices support an iothread parameter.
4075
4076                     The  query-iothreads  QMP  command  lists  IOThreads  and
4077                     reports their thread IDs so that the user  can  configure
4078                     host CPU pinning/affinity.
4079
4080                     IOThreads  use  an  adaptive  polling algorithm to reduce
4081                     event loop latency. Instead of entering a blocking system
4082                     call to monitor file descriptors and then pay the cost of
4083                     being woken up when an event occurs,  the  polling  algo‐
4084                     rithm  spins  waiting  for  events  for a short time. The
4085                     algorithm's default  parameters  are  suitable  for  many
4086                     cases but can be adjusted based on knowledge of the work‐
4087                     load and/or host device latency.
4088
4089                     The  poll-max-ns  parameter  is  the  maximum  number  of
4090                     nanoseconds  to busy wait for events. Polling can be dis‐
4091                     abled by setting this value to 0.
4092
4093                     The  poll-grow  parameter  is  the  multiplier  used   to
4094                     increase  the  polling time when the algorithm detects it
4095                     is missing events due to not polling long enough.
4096
4097                     The poll-shrink parameter is the divisor used to decrease
4098                     the  polling time when the algorithm detects it is spend‐
4099                     ing too long polling without encountering events.
4100
4101                     The polling parameters can be modified at run-time  using
4102                     the  qom-set  command  (where iothread1 is the IOThread's
4103                     id):
4104
4105                        (qemu) qom-set /objects/iothread1 poll-max-ns 100000
4106
4107       During the graphical emulation, you can use special key combinations to
4108       change  modes. The default key mappings are shown below, but if you use
4109       -alt-grab then the modifier is Ctrl-Alt-Shift (instead of Ctrl-Alt) and
4110       if  you use -ctrl-grab then the modifier is the right Ctrl key (instead
4111       of Ctrl-Alt):
4112
4113       Ctrl-Alt-f
4114              Toggle full screen
4115
4116       Ctrl-Alt-+
4117              Enlarge the screen
4118
4119       Ctrl-Alt--
4120              Shrink the screen
4121
4122       Ctrl-Alt-u
4123              Restore the screen's un-scaled dimensions
4124
4125       Ctrl-Alt-n
4126              Switch to virtual console 'n'. Standard console mappings are:
4127
4128              1      Target system display
4129
4130              2      Monitor
4131
4132              3      Serial port
4133
4134       Ctrl-Alt
4135              Toggle mouse and keyboard grab.
4136
4137       In the virtual consoles, you can use  Ctrl-Up,  Ctrl-Down,  Ctrl-PageUp
4138       and Ctrl-PageDown to move in the back log.
4139
4140       During  emulation,  if  you  are  using a character backend multiplexer
4141       (which is the default if you are using -nographic)  then  several  com‐
4142       mands  are  available  via  an escape sequence. These key sequences all
4143       start with an escape character, which is Ctrl-a by default, but can  be
4144       changed with -echr. The list below assumes you're using the default.
4145
4146       Ctrl-a h
4147              Print this help
4148
4149       Ctrl-a x
4150              Exit emulator
4151
4152       Ctrl-a s
4153              Save disk data back to file (if -snapshot)
4154
4155       Ctrl-a t
4156              Toggle console timestamps
4157
4158       Ctrl-a b
4159              Send break (magic sysrq in Linux)
4160
4161       Ctrl-a c
4162              Rotate  between the frontends connected to the multiplexer (usu‐
4163              ally this switches between the monitor and the console)
4164
4165       Ctrl-a Ctrl-a
4166              Send the escape character to the frontend
4167

NOTES

4169       In addition to using  normal  file  images  for  the  emulated  storage
4170       devices,  QEMU  can also use networked resources such as iSCSI devices.
4171       These are specified using a special URL syntax.
4172
4173       iSCSI  iSCSI support allows QEMU to access iSCSI resources directly and
4174              use  as images for the guest storage. Both disk and cdrom images
4175              are supported.
4176
4177              Syntax   for   specifying   iSCSI   LUNs    is    "iscsi://<tar‐
4178              get-ip>[:<port>]/<target-iqn>/<lun>"
4179
4180              By    default   qemu   will   use   the   iSCSI   initiator-name
4181              'iqn.2008-11.org.linux-kvm[:<name>]' but this can  also  be  set
4182              from the command line or a configuration file.
4183
4184              Since version Qemu 2.4 it is possible to specify a iSCSI request
4185              timeout to detect stalled requests and force  a  reestablishment
4186              of the session. The timeout is specified in seconds. The default
4187              is 0 which means no  timeout.  Libiscsi  1.15.0  or  greater  is
4188              required for this feature.
4189
4190              Example (without authentication):
4191
4192                 qemu-system-x86_64 -iscsi initiator-name=iqn.2001-04.com.example:my-initiator                  -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2                  -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
4193
4194              Example (CHAP username/password via URL):
4195
4196                 qemu-system-x86_64 -drive file=iscsi://user%password@192.0.2.1/iqn.2001-04.com.example/1
4197
4198              Example (CHAP username/password via environment variables):
4199
4200                 LIBISCSI_CHAP_USERNAME="user" LIBISCSI_CHAP_PASSWORD="password" qemu-system-x86_64 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
4201
4202       NBD    QEMU  supports NBD (Network Block Devices) both using TCP proto‐
4203              col as well as Unix Domain Sockets. With TCP, the  default  port
4204              is 10809.
4205
4206              Syntax  for  specifying a NBD device using TCP, in preferred URI
4207              form: "nbd://<server-ip>[:<port>]/[<export>]"
4208
4209              Syntax for specifying a NBD device using  Unix  Domain  Sockets;
4210              remember  that  '?' is a shell glob character and may need quot‐
4211              ing: "nbd+unix:///[<export>]?socket=<domain-socket>"
4212
4213              Older      syntax      that      is       also       recognized:
4214              "nbd:<server-ip>:<port>[:exportname=<export>]"
4215
4216              Syntax  for  specifying  a  NBD device using Unix Domain Sockets
4217              "nbd:unix:<domain-socket>[:exportname=<export>]"
4218
4219              Example for TCP
4220
4221                 qemu-system-x86_64 --drive file=nbd:192.0.2.1:30000
4222
4223              Example for Unix Domain Sockets
4224
4225                 qemu-system-x86_64 --drive file=nbd:unix:/tmp/nbd-socket
4226
4227       SSH    QEMU supports SSH (Secure Shell) access to remote disks.
4228
4229              Examples:
4230
4231                 qemu-system-x86_64 -drive file=ssh://user@host/path/to/disk.img
4232                 qemu-system-x86_64 -drive file.driver=ssh,file.user=user,file.host=host,file.port=22,file.path=/path/to/disk.img
4233
4234              Currently authentication must be  done  using  ssh-agent.  Other
4235              authentication methods may be supported in future.
4236
4237       Sheepdog
4238              Sheepdog is a distributed storage system for QEMU. QEMU supports
4239              using either local sheepdog devices or remote networked devices.
4240
4241              Syntax for specifying a sheepdog device
4242
4243                 sheepdog[+tcp|+unix]://[host:port]/vdiname[?socket=path][#snapid|#tag]
4244
4245              Example
4246
4247                 qemu-system-x86_64 --drive file=sheepdog://192.0.2.1:30000/MyVirtualMachine
4248
4249              See also https://sheepdog.github.io/sheepdog/.
4250
4251       GlusterFS
4252              GlusterFS is a user space distributed file system. QEMU supports
4253              the  use  of  GlusterFS volumes for hosting VM disk images using
4254              TCP, Unix Domain Sockets and RDMA transport protocols.
4255
4256              Syntax for specifying a VM disk image on GlusterFS volume is
4257
4258                 URI:
4259                 gluster[+type]://[host[:port]]/volume/path[?socket=...][,debug=N][,logfile=...]
4260
4261                 JSON:
4262                 'json:{"driver":"qcow2","file":{"driver":"gluster","volume":"testvol","path":"a.img","debug":N,"logfile":"...",
4263                                                  "server":[{"type":"tcp","host":"...","port":"..."},
4264                                                            {"type":"unix","socket":"..."}]}}'
4265
4266              Example
4267
4268                 URI:
4269                 qemu-system-x86_64 --drive file=gluster://192.0.2.1/testvol/a.img,
4270                                                file.debug=9,file.logfile=/var/log/qemu-gluster.log
4271
4272                 JSON:
4273                 qemu-system-x86_64 'json:{"driver":"qcow2",
4274                                           "file":{"driver":"gluster",
4275                                                    "volume":"testvol","path":"a.img",
4276                                                    "debug":9,"logfile":"/var/log/qemu-gluster.log",
4277                                                    "server":[{"type":"tcp","host":"1.2.3.4","port":24007},
4278                                                              {"type":"unix","socket":"/var/run/glusterd.socket"}]}}'
4279                 qemu-system-x86_64 -drive driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img,
4280                                                       file.debug=9,file.logfile=/var/log/qemu-gluster.log,
4281                                                       file.server.0.type=tcp,file.server.0.host=1.2.3.4,file.server.0.port=24007,
4282                                                       file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket
4283
4284              See also http://www.gluster.org.
4285
4286       HTTP/HTTPS/FTP/FTPS
4287              QEMU supports read-only access to files  accessed  over  http(s)
4288              and ftp(s).
4289
4290              Syntax using a single filename:
4291
4292                 <protocol>://[<username>[:<password>]@]<host>/<path>
4293
4294              where:
4295
4296              protocol
4297                     'http', 'https', 'ftp', or 'ftps'.
4298
4299              username
4300                     Optional   username  for  authentication  to  the  remote
4301                     server.
4302
4303              password
4304                     Optional  password  for  authentication  to  the   remote
4305                     server.
4306
4307              host   Address of the remote server.
4308
4309              path   Path on the remote server, including any query string.
4310
4311              The following options are also supported:
4312
4313              url    The  full  URL when passing options to the driver explic‐
4314                     itly.
4315
4316              readahead
4317                     The amount of data to read ahead with each range  request
4318                     to  the remote server. This value may optionally have the
4319                     suffix 'T', 'G', 'M', 'K', 'k' or 'b'.  If  it  does  not
4320                     have  a  suffix,  it  will be assumed to be in bytes. The
4321                     value must be a multiple of 512 bytes.   It  defaults  to
4322                     256k.
4323
4324              sslverify
4325                     Whether  to  verify  the remote server's certificate when
4326                     connecting over SSL. It can have the value 'on' or 'off'.
4327                     It defaults to 'on'.
4328
4329              cookie Send  this cookie (it can also be a list of cookies sepa‐
4330                     rated by ';') with each outgoing request. Only  supported
4331                     when  using protocols such as HTTP which support cookies,
4332                     otherwise ignored.
4333
4334              timeout
4335                     Set the timeout in seconds of the CURL  connection.  This
4336                     timeout  is  the time that CURL waits for a response from
4337                     the remote server to get the size  of  the  image  to  be
4338                     downloaded.  If not set, the default timeout of 5 seconds
4339                     is used.
4340
4341              Note that when passing options to qemu explicitly, driver is the
4342              value of <protocol>.
4343
4344              Example: boot from a remote Fedora 20 live ISO image
4345
4346                 qemu_system-x86_64 --drive media=cdrom,file=https://archives.fedoraproject.org/pub/archive/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly
4347
4348                 qemu_system-x86_64 --drive media=cdrom,file.driver=http,file.url=http://archives.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly
4349
4350              Example:  boot from a remote Fedora 20 cloud image using a local
4351              overlay for writes, copy-on-read, and a readahead of 64k
4352
4353                 qemu-img create -f qcow2 -o backing_file='json:{"file.driver":"http",, "file.url":"http://archives.fedoraproject.org/pub/archive/fedora/linux/releases/20/Images/x86_64/Fedora-x86_64-20-20131211.1-sda.qcow2",, "file.readahead":"64k"}' /tmp/Fedora-x86_64-20-20131211.1-sda.qcow2
4354
4355                 qemu_system-x86_64 -drive file=/tmp/Fedora-x86_64-20-20131211.1-sda.qcow2,copy-on-read=on
4356
4357              Example: boot from an image stored on a  VMware  vSphere  server
4358              with a self-signed certificate using a local overlay for writes,
4359              a readahead of 64k and a timeout of 10 seconds.
4360
4361                 qemu-img create -f qcow2 -o backing_file='json:{"file.driver":"https",, "file.url":"https://user:password@vsphere.example.com/folder/test/test-flat.vmdk?dcPath=Datacenter&dsName=datastore1",, "file.sslverify":"off",, "file.readahead":"64k",, "file.timeout":10}' /tmp/test.qcow2
4362
4363                 qemu_system-x86_64 -drive file=/tmp/test.qcow2
4364

SEE ALSO

4366       The HTML documentation of QEMU for more precise information  and  Linux
4367       user mode emulator invocation.
4368

AUTHOR

4370       Fabrice Bellard
4371
4373       2021, The QEMU Project Developers
4374
4375
4376
4377
43785.1.0                            Jan 11, 2021                          QEMU(1)
Impressum