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

NOTES

4245       In  addition  to  using normal file images for the emulated storage de‐
4246       vices, QEMU can also use networked resources  such  as  iSCSI  devices.
4247       These are specified using a special URL syntax.
4248
4249       iSCSI  iSCSI support allows QEMU to access iSCSI resources directly and
4250              use as images for the guest storage. Both disk and cdrom  images
4251              are supported.
4252
4253              Syntax    for    specifying   iSCSI   LUNs   is   "iscsi://<tar‐
4254              get-ip>[:<port>]/<target-iqn>/<lun>"
4255
4256              By   default   qemu   will   use   the   iSCSI    initiator-name
4257              'iqn.2008-11.org.linux-kvm[:<name>]'  but  this  can also be set
4258              from the command line or a configuration file.
4259
4260              Since version Qemu 2.4 it is possible to specify a iSCSI request
4261              timeout  to  detect stalled requests and force a reestablishment
4262              of the session. The timeout is specified in seconds. The default
4263              is  0  which means no timeout. Libiscsi 1.15.0 or greater is re‐
4264              quired for this feature.
4265
4266              Example (without authentication):
4267
4268                 qemu-system-x86_64 -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \
4269                                  -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \
4270                                  -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
4271
4272              Example (CHAP username/password via URL):
4273
4274                 qemu-system-x86_64 -drive file=iscsi://user%password@192.0.2.1/iqn.2001-04.com.example/1
4275
4276              Example (CHAP username/password via environment variables):
4277
4278                 LIBISCSI_CHAP_USERNAME="user" \
4279                 LIBISCSI_CHAP_PASSWORD="password" \
4280                 qemu-system-x86_64 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
4281
4282       NBD    QEMU supports NBD (Network Block Devices) both using TCP  proto‐
4283              col  as  well as Unix Domain Sockets. With TCP, the default port
4284              is 10809.
4285
4286              Syntax for specifying a NBD device using TCP, in  preferred  URI
4287              form: "nbd://<server-ip>[:<port>]/[<export>]"
4288
4289              Syntax  for  specifying  a NBD device using Unix Domain Sockets;
4290              remember that '?' is a shell glob character and may  need  quot‐
4291              ing: "nbd+unix:///[<export>]?socket=<domain-socket>"
4292
4293              Older       syntax       that      is      also      recognized:
4294              "nbd:<server-ip>:<port>[:exportname=<export>]"
4295
4296              Syntax for specifying a NBD device  using  Unix  Domain  Sockets
4297              "nbd:unix:<domain-socket>[:exportname=<export>]"
4298
4299              Example for TCP
4300
4301                 qemu-system-x86_64 --drive file=nbd:192.0.2.1:30000
4302
4303              Example for Unix Domain Sockets
4304
4305                 qemu-system-x86_64 --drive file=nbd:unix:/tmp/nbd-socket
4306
4307       SSH    QEMU supports SSH (Secure Shell) access to remote disks.
4308
4309              Examples:
4310
4311                 qemu-system-x86_64 -drive file=ssh://user@host/path/to/disk.img
4312                 qemu-system-x86_64 -drive file.driver=ssh,file.user=user,file.host=host,file.port=22,file.path=/path/to/disk.img
4313
4314              Currently authentication must be done using ssh-agent. Other au‐
4315              thentication methods may be supported in future.
4316
4317       Sheepdog
4318              Sheepdog is a distributed storage system for QEMU. QEMU supports
4319              using either local sheepdog devices or remote networked devices.
4320
4321              Syntax for specifying a sheepdog device
4322
4323                 sheepdog[+tcp|+unix]://[host:port]/vdiname[?socket=path][#snapid|#tag]
4324
4325              Example
4326
4327                 qemu-system-x86_64 --drive file=sheepdog://192.0.2.1:30000/MyVirtualMachine
4328
4329              See also https://sheepdog.github.io/sheepdog/.
4330
4331       GlusterFS
4332              GlusterFS is a user space distributed file system. QEMU supports
4333              the use of GlusterFS volumes for hosting VM  disk  images  using
4334              TCP, Unix Domain Sockets and RDMA transport protocols.
4335
4336              Syntax for specifying a VM disk image on GlusterFS volume is
4337
4338                 URI:
4339                 gluster[+type]://[host[:port]]/volume/path[?socket=...][,debug=N][,logfile=...]
4340
4341                 JSON:
4342                 'json:{"driver":"qcow2","file":{"driver":"gluster","volume":"testvol","path":"a.img","debug":N,"logfile":"...",
4343                                                  "server":[{"type":"tcp","host":"...","port":"..."},
4344                                                            {"type":"unix","socket":"..."}]}}'
4345
4346              Example
4347
4348                 URI:
4349                 qemu-system-x86_64 --drive file=gluster://192.0.2.1/testvol/a.img,
4350                                                file.debug=9,file.logfile=/var/log/qemu-gluster.log
4351
4352                 JSON:
4353                 qemu-system-x86_64 'json:{"driver":"qcow2",
4354                                           "file":{"driver":"gluster",
4355                                                    "volume":"testvol","path":"a.img",
4356                                                    "debug":9,"logfile":"/var/log/qemu-gluster.log",
4357                                                    "server":[{"type":"tcp","host":"1.2.3.4","port":24007},
4358                                                              {"type":"unix","socket":"/var/run/glusterd.socket"}]}}'
4359                 qemu-system-x86_64 -drive driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img,
4360                                                       file.debug=9,file.logfile=/var/log/qemu-gluster.log,
4361                                                       file.server.0.type=tcp,file.server.0.host=1.2.3.4,file.server.0.port=24007,
4362                                                       file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket
4363
4364              See also http://www.gluster.org.
4365
4366       HTTP/HTTPS/FTP/FTPS
4367              QEMU  supports  read-only  access to files accessed over http(s)
4368              and ftp(s).
4369
4370              Syntax using a single filename:
4371
4372                 <protocol>://[<username>[:<password>]@]<host>/<path>
4373
4374              where:
4375
4376              protocol
4377                     'http', 'https', 'ftp', or 'ftps'.
4378
4379              username
4380                     Optional  username  for  authentication  to  the   remote
4381                     server.
4382
4383              password
4384                     Optional   password  for  authentication  to  the  remote
4385                     server.
4386
4387              host   Address of the remote server.
4388
4389              path   Path on the remote server, including any query string.
4390
4391              The following options are also supported:
4392
4393              url    The full URL when passing options to the  driver  explic‐
4394                     itly.
4395
4396              readahead
4397                     The  amount of data to read ahead with each range request
4398                     to the remote server. This value may optionally have  the
4399                     suffix  'T',  'G',  'M',  'K', 'k' or 'b'. If it does not
4400                     have a suffix, it will be assumed to  be  in  bytes.  The
4401                     value  must  be  a multiple of 512 bytes.  It defaults to
4402                     256k.
4403
4404              sslverify
4405                     Whether to verify the remote  server's  certificate  when
4406                     connecting over SSL. It can have the value 'on' or 'off'.
4407                     It defaults to 'on'.
4408
4409              cookie Send this cookie (it can also be a list of cookies  sepa‐
4410                     rated  by ';') with each outgoing request. Only supported
4411                     when using protocols such as HTTP which support  cookies,
4412                     otherwise ignored.
4413
4414              timeout
4415                     Set  the  timeout in seconds of the CURL connection. This
4416                     timeout is the time that CURL waits for a  response  from
4417                     the  remote  server  to  get  the size of the image to be
4418                     downloaded. If not set, the default timeout of 5  seconds
4419                     is used.
4420
4421              Note that when passing options to qemu explicitly, driver is the
4422              value of <protocol>.
4423
4424              Example: boot from a remote Fedora 20 live ISO image
4425
4426                 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
4427
4428                 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
4429
4430              Example: boot from a remote Fedora 20 cloud image using a  local
4431              overlay for writes, copy-on-read, and a readahead of 64k
4432
4433                 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
4434
4435                 qemu_system-x86_64 -drive file=/tmp/Fedora-x86_64-20-20131211.1-sda.qcow2,copy-on-read=on
4436
4437              Example:  boot  from  an image stored on a VMware vSphere server
4438              with a self-signed certificate using a local overlay for writes,
4439              a readahead of 64k and a timeout of 10 seconds.
4440
4441                 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
4442
4443                 qemu_system-x86_64 -drive file=/tmp/test.qcow2
4444

SEE ALSO

4446       The  HTML  documentation of QEMU for more precise information and Linux
4447       user mode emulator invocation.
4448

AUTHOR

4450       Fabrice Bellard
4451
4453       2021, The QEMU Project Developers
4454
4455
4456
4457
44585.2.0                            May 19, 2021                          QEMU(1)
Impressum