318
346
only needed by Xen fully virtualized domains. <span class="since">Since 0.1.0</span></dd><dt><code>boot</code></dt><dd>The <code>dev</code> attribute takes one of the values "fd", "hd",
319
347
"cdrom" or "network" and is used to specify the next boot device
320
348
to consider. The <code>boot</code> element can be repeated multiple
321
times to setup a priority list of boot devices to try in turn.
322
<span class="since">Since 0.1.3</span>
349
times to setup a priority list of boot devices to try in turn. The
350
<code>boot</code> element cannot be used if per-device boot elements
351
are used (see <a href="#elementsDisks">disks</a>,
352
<a href="#elementsNICS">network interfaces</a>, and
353
<a href="#elementsUSB">USB and PCI devices</a> sections below).
354
<span class="since">Since 0.1.3, per-device boot since 0.8.8</span>
323
355
</dd><dt><code>bootmenu</code></dt><dd> Whether or not to enable an interactive boot menu prompt on guest
324
356
startup. The <code>enable</code> attribute can be either "yes" or "no".
325
357
If not specified, the hypervisor default is used. <span class="since">
326
358
Since 0.8.3</span>
359
</dd><dt><code>smbios</code></dt><dd>How to populate SMBIOS information visible in the guest.
360
The <code>mode</code> attribute must be specified, and is either
361
"emulate" (let the hypervisor generate all values), "host" (copy
362
all of Block 0 and Block 1, except for the UUID, from the host's
364
the <a href="html/libvirt-libvirt.html#virConnectGetSysinfo">
365
<code>virConnectGetSysinfo</code></a> call can be
366
used to see what values are copied), or "sysinfo" (use the values in
367
the <a href="#elementsSysinfo">sysinfo</a> element). If not
368
specified, the hypervisor default is used. <span class="since">
329
372
<a name="elementsOSBootloader" id="elementsOSBootloader">Host bootloader</a>
376
419
specify an alternate primary console (eg serial port), or the
377
420
installation media source / kickstart file</dd></dl>
422
<a name="elementsSysinfo" id="elementsSysinfo">SMBIOS System Information</a>
425
Some hypervisors allow control over what system information is
426
presented to the guest (for example, SMBIOS fields can be
427
populated by a hypervisor and inspected via
428
the <code>dmidecode</code> command in the guest). The
429
optional <code>sysinfo</code> element covers all such categories
430
of information. <span class="since">Since 0.8.7</span>
435
<smbios mode='sysinfo'/>
438
<sysinfo type='smbios'>
440
<entry name='vendor'>LENOVO</entry>
443
<entry name='manufacturer'>Fedora</entry>
444
<entry name='vendor'>Virt-Manager</entry>
449
The <code>sysinfo</code> element has a mandatory
450
attribute <code>type</code> that determine the layout of
451
sub-elements, with supported values of:
453
<dl><dt><code>smbios</code></dt><dd>Sub-elements call out specific SMBIOS values, which will
454
affect the guest if used in conjunction with
455
the <code>smbios</code> sub-element of
456
the <a href="#elementsOS"><code>os</code></a> element. Each
457
sub-element of <code>sysinfo</code> names a SMBIOS block, and
458
within those elements can be a list of <code>entry</code>
459
elements that describe a field within the block. The following
460
blocks and entries are recognized:
461
<dl><dt><code>bios</code></dt><dd>
462
This is block 0 of SMBIOS, with entry names drawn from
463
"vendor", "version", "date", and "release".
464
</dd><dt><code>system</code></dt><dd>
465
This is block 1 of SMBIOS, with entry names drawn from
466
"manufacturer", "product", "version", "serial", "uuid",
467
"sku", and "family". If a "uuid" entry is provided
469
top-level <a href="#elementsMetadata"><code>uuid</code>
470
element</a>, the two values must match.
379
473
<a name="elementsResources" id="elementsResources">Basic resources</a>
394
491
<vcpu cpuset="1-4,^3,6" current="1">2</vcpu>
396
493
<dl><dt><code>memory</code></dt><dd>The maximum allocation of memory for the guest at boot time.
397
The units for this value are kilobytes (i.e. blocks of 1024 bytes)</dd><dt><code>currentMemory</code></dt><dd>The actual allocation of memory for the guest. This value
494
The units for this value are kilobytes (i.e. blocks of 1024 bytes)</dd><dt><code>currentMemory</code></dt><dd>The actual allocation of memory for the guest. This value can
398
495
be less than the maximum allocation, to allow for ballooning
399
496
up the guests memory on the fly. If this is omitted, it defaults
400
to the same value as the <code>memory<code> element</code></code></dd><dt><code>memoryBacking</code></dt><dd>The optional <code>memoryBacking</code> element, may have an
497
to the same value as the <code>memory</code> element</dd><dt><code>memoryBacking</code></dt><dd>The optional <code>memoryBacking</code> element, may have an
401
498
<code>hugepages</code> element set within it. This tells the
402
499
hypervisor that the guest should have its memory allocated using
403
hugepages instead of the normal native page size.</dd><dt><code>memtune</code></dt><dd> The optional <code>memtune</code> element provides details
404
regarding the memory tuneable parameters for the domain. If this is
405
omitted, it defaults to the OS provided defaults.</dd><dt><code>hard_limit</code></dt><dd> The optional <code>hard_limit</code> element is the maximum memory
406
the guest can use. The units for this value are kilobytes (i.e. blocks
407
of 1024 bytes)</dd><dt><code>soft_limit</code></dt><dd> The optional <code>soft_limit</code> element is the memory limit to
408
enforce during memory contention. The units for this value are
409
kilobytes (i.e. blocks of 1024 bytes)</dd><dt><code>swap_hard_limit</code></dt><dd> The optional <code>swap_hard_limit</code> element is the maximum
410
swap the guest can use. The units for this value are kilobytes
411
(i.e. blocks of 1024 bytes)</dd><dt><code>min_guarantee</code></dt><dd> The optional <code>min_guarantee</code> element is the guaranteed
412
minimum memory allocation for the guest. The units for this value are
413
kilobytes (i.e. blocks of 1024 bytes)</dd><dt><code>vcpu</code></dt><dd>The content of this element defines the maximum number of virtual
500
hugepages instead of the normal native page size.</dd><dt><code>blkiotune</code></dt><dd> The optional <code>blkiotune</code> element provides the ability
501
to tune Blkio cgroup tunable parameters for the domain. If this is
502
omitted, it defaults to the OS provided defaults.</dd><dt><code>weight</code></dt><dd> The optional <code>weight</code> element is the I/O weight of the
503
guest. The value should be in range [100, 1000].</dd><dt><code>memtune</code></dt><dd> The optional <code>memtune</code> element provides details
504
regarding the memory tunable parameters for the domain. If this is
505
omitted, it defaults to the OS provided defaults.</dd><dt><code>hard_limit</code></dt><dd> The optional <code>hard_limit</code> element is the maximum memory
506
the guest can use. The units for this value are kilobytes (i.e. blocks
507
of 1024 bytes)</dd><dt><code>soft_limit</code></dt><dd> The optional <code>soft_limit</code> element is the memory limit to
508
enforce during memory contention. The units for this value are
509
kilobytes (i.e. blocks of 1024 bytes)</dd><dt><code>swap_hard_limit</code></dt><dd> The optional <code>swap_hard_limit</code> element is the maximum
510
swap the guest can use. The units for this value are kilobytes
511
(i.e. blocks of 1024 bytes)</dd><dt><code>min_guarantee</code></dt><dd> The optional <code>min_guarantee</code> element is the guaranteed
512
minimum memory allocation for the guest. The units for this value are
513
kilobytes (i.e. blocks of 1024 bytes)</dd><dt><code>vcpu</code></dt><dd>The content of this element defines the maximum number of virtual
414
514
CPUs allocated for the guest OS, which must be between 1 and
415
515
the maximum supported by the hypervisor. <span class="since">Since
416
516
0.4.4</span>, this element can contain an optional
573
676
<dl><dt><code>clock</code></dt><dd>
574
<p>The <code>offset</code> attribute takes four possible
575
values, allowing fine grained control over how the guest
576
clock is synchronized to the host. NB, not all hypervisors
577
support all modes.</p>
578
<dl><dt><code>utc</code></dt><dd>
579
The guest clock will always be synchronized to UTC when
580
booted</dd><dt><code>localtime</code></dt><dd>
581
The guest clock will be synchronized to the host's configured
582
timezone when booted, if any.
583
</dd><dt><code>timezone</code></dt><dd>
584
The guest clock will be synchronized to the requested timezone
585
using the <code>timezone</code> attribute.
586
<span class="since">Since 0.7.7</span>
587
</dd><dt><code>variable</code></dt><dd>
588
The guest clock will have an arbitrary offset applied
589
relative to UTC. The delta relative to UTC is specified
590
in seconds, using the <code>adjustment</code> attribute.
591
The guest is free to adjust the RTC over time an expect
592
that it will be honoured at next reboot. This is in
593
contrast to 'utc' mode, where the RTC adjustments are
594
lost at each reboot. <span class="since">Since 0.7.7</span>
596
A <code>clock</code> may have zero or more
597
<code>timer</code>sub-elements. <span class="since">Since
677
<p>The <code>offset</code> attribute takes four possible
678
values, allowing fine grained control over how the guest
679
clock is synchronized to the host. NB, not all hypervisors
680
support all modes.</p>
681
<dl><dt><code>utc</code></dt><dd>
682
The guest clock will always be synchronized to UTC when
683
booted</dd><dt><code>localtime</code></dt><dd>
684
The guest clock will be synchronized to the host's configured
685
timezone when booted, if any.
686
</dd><dt><code>timezone</code></dt><dd>
687
The guest clock will be synchronized to the requested timezone
688
using the <code>timezone</code> attribute.
689
<span class="since">Since 0.7.7</span>
690
</dd><dt><code>variable</code></dt><dd>
691
The guest clock will have an arbitrary offset applied
692
relative to UTC. The delta relative to UTC is specified
693
in seconds, using the <code>adjustment</code> attribute.
694
The guest is free to adjust the RTC over time an expect
695
that it will be honoured at next reboot. This is in
696
contrast to 'utc' mode, where the RTC adjustments are
697
lost at each reboot. <span class="since">Since 0.7.7</span>
699
A <code>clock</code> may have zero or more
700
<code>timer</code>sub-elements. <span class="since">Since
600
703
</dd><dt><code>timer</code></dt><dd>
602
Each timer element requires a <code>name</code> attribute,
603
and has other optional attributes that depend on
604
the <code>name</code> specified. Various hypervisors
605
support different combinations of attributes.
607
<dl><dt><code>name</code></dt><dd>
608
The <code>name</code> attribute selects which timer is
609
being modified, and can be one of "platform", "pit",
610
"rtc", "hpet", or "tsc".
611
</dd><dt><code>track</code></dt><dd>
612
The <code>track</code> attribute specifies what the timer
613
tracks, and can be "boot", "guest", or "wall".
614
Only valid for <code>name="rtc"</code>
615
or <code>name="platform"</code>.
616
</dd><dt><code>tickpolicy</code></dt><dd>
617
The <code>tickpolicy</code> attribute determines how
618
missed ticks in the guest are handled, and can be "delay",
619
"catchup", "merge", or "discard". If the policy is
620
"catchup", there can be further details in
621
the <code>catchup</code> sub-element.
622
<dl><dt><code>catchup</code></dt><dd>
623
The <code>catchup</code> element has three optional
624
attributes, each a positive integer. The attributes
625
are <code>threshold</code>, <code>slew</code>,
626
and <code>limit</code>.
627
</dd></dl></dd><dt><code>frequency</code></dt><dd>
628
The <code>frequency</code> attribute is an unsigned
629
integer specifying the frequency at
630
which <code>name="tsc"</code> runs.
631
</dd><dt><code>mode</code></dt><dd>
632
The <code>mode</code> attribute controls how
633
the <code>name="tsc"</code> timer is managed, and can be
634
"auto", "native", "emulate", "paravirt", or "smpsafe".
635
Other timers are always emulated.
636
</dd><dt><code>present</code></dt><dd>
637
The <code>present</code> attribute can be "yes" or "no" to
638
specify whether a particular timer is available to the guest.
705
Each timer element requires a <code>name</code> attribute,
706
and has other optional attributes that depend on
707
the <code>name</code> specified. Various hypervisors
708
support different combinations of attributes.
710
<dl><dt><code>name</code></dt><dd>
711
The <code>name</code> attribute selects which timer is
712
being modified, and can be one of "platform", "pit",
713
"rtc", "hpet", or "tsc".
714
</dd><dt><code>track</code></dt><dd>
715
The <code>track</code> attribute specifies what the timer
716
tracks, and can be "boot", "guest", or "wall".
717
Only valid for <code>name="rtc"</code>
718
or <code>name="platform"</code>.
719
</dd><dt><code>tickpolicy</code></dt><dd>
720
The <code>tickpolicy</code> attribute determines how
721
missed ticks in the guest are handled, and can be "delay",
722
"catchup", "merge", or "discard". If the policy is
723
"catchup", there can be further details in
724
the <code>catchup</code> sub-element.
725
<dl><dt><code>catchup</code></dt><dd>
726
The <code>catchup</code> element has three optional
727
attributes, each a positive integer. The attributes
728
are <code>threshold</code>, <code>slew</code>,
729
and <code>limit</code>.
730
</dd></dl></dd><dt><code>frequency</code></dt><dd>
731
The <code>frequency</code> attribute is an unsigned
732
integer specifying the frequency at
733
which <code>name="tsc"</code> runs.
734
</dd><dt><code>mode</code></dt><dd>
735
The <code>mode</code> attribute controls how
736
the <code>name="tsc"</code> timer is managed, and can be
737
"auto", "native", "emulate", "paravirt", or "smpsafe".
738
Other timers are always emulated.
739
</dd><dt><code>present</code></dt><dd>
740
The <code>present</code> attribute can be "yes" or "no" to
741
specify whether a particular timer is available to the guest.
641
744
<a name="elementsDevices" id="elementsDevices">Devices</a>
790
<disk type='network'>
791
<driver name="qemu" type="raw" io="threads"/>
792
<source protocol="sheepdog" name="image_name">
793
<host name="hostname" port="7000"/>
795
<target dev="hdb" bus="ide"/>
796
<boot order='1'/>
797
<address type='drive' controller='0' bus='1' unit='0'/>
687
801
<dl><dt><code>disk</code></dt><dd>The <code>disk</code> element is the main container for describing
688
disks. The <code>type</code> attribute is either "file" or "block"
802
disks. The <code>type</code> attribute is either "file",
803
"block", "dir", or "network"
689
804
and refers to the underlying source for the disk. The optional
690
805
<code>device</code> attribute indicates how the disk is to be exposed
691
806
to the guest OS. Possible values for this attribute are "floppy", "disk"
692
807
and "cdrom", defaulting to "disk".
693
<span class="since">Since 0.0.3; "device" attribute since 0.1.4</span></dd><dt><code>source</code></dt><dd>If the disk <code>type</code> is "file", then the <code>file</code> attribute
694
specifies the fully-qualified path to the file holding the disk. If the disk
695
<code>type</code> is "block", then the <code>dev</code> attribute specifies
696
the path to the host device to serve as the disk. <span class="since">Since 0.0.3</span></dd><dt><code>target</code></dt><dd>The <code>target</code> element controls the bus / device under which the
808
<span class="since">Since 0.0.3; "device" attribute since 0.1.4;
809
"network" attribute since 0.8.7</span></dd><dt><code>source</code></dt><dd>If the disk <code>type</code> is "file", then the
810
the <code>file</code> attribute specifies the fully-qualified
811
path to the file holding the disk. If the disk
812
<code>type</code> is "block", then the <code>dev</code>
813
attribute specifies the path to the host device to serve as
814
the disk. If the disk <code>type</code> is "network", then
815
the <code>protocol</code> attribute specifies the protocol to
816
access to the requested image; possible values are "nbd",
817
"rbd", and "sheepdog". If the <code>protocol</code> attribute
818
is "rbd" or "sheepdog", an additional
819
attribute <code>name</code> is mandatory to specify which
820
image to be used. When the disk <code>type</code> is
821
"network", the <code>source</code> may have zero or
822
more <code>host</code> sub-elements used to specify the hosts
824
<span class="since">Since 0.0.3</span></dd><dt><code>target</code></dt><dd>The <code>target</code> element controls the bus / device under which the
697
825
disk is exposed to the guest OS. The <code>dev</code> attribute indicates
698
826
the "logical" device name. The actual device name specified is not guaranteed to map to
699
827
the device name in the guest OS. Treat it as a device ordering hint.
703
831
inferred from the style of the device name. eg, a device named 'sda'
704
832
will typically be exported using a SCSI bus.
705
833
<span class="since">Since 0.0.3; <code>bus</code> attribute since 0.4.3;
706
"usb" attribute value since after 0.4.4</span></dd><dt><code>driver</code></dt><dd>If the hypervisor supports multiple backend drivers, then the optional
707
<code>driver</code> element allows them to be selected. The <code>name</code>
708
attribute is the primary backend driver name, while the optional <code>type</code>
709
attribute provides the sub-type. The optional <code>cache</code> attribute
710
controls the cache mechanism, possible values are "default", "none",
711
"writethrough" and "writeback". <span class="since">Since 0.1.8</span>
834
"usb" attribute value since after 0.4.4</span></dd><dt><code>driver</code></dt><dd>
835
The optional driver element allows specifying further details
836
related to the hypervisor driver used to provide the disk.
837
<span class="since">Since 0.1.8; <code>io</code> attribute
840
If the hypervisor supports multiple backend drivers, then
841
the <code>name</code> attribute selects the primary
842
backend driver name, while the optional <code>type</code>
843
attribute provides the sub-type. For example, xen
844
supports a name of "tap", "tap2", "phy", or "file", with a
845
type of "aio", while qemu only supports a name of "qemu",
846
but multiple types including "raw", "bochs", "qcow2", and
849
The optional <code>cache</code> attribute controls the
850
cache mechanism, possible values are "default", "none",
851
"writethrough" and "writeback".
853
The optional <code>error_policy</code> attribute controls
854
how the hypervisor will behave on an error, possible
855
values are "stop", "ignore", and "enospace".
857
The optional <code>io</code> attribute controls specific
858
policies on I/O; qemu guests support "threads" and
860
</li></ul></dd><dt><code>boot</code></dt><dd>Specifies that the disk is bootable. The <code>order</code>
861
attribute determines the order in which devices will be tried during
862
boot sequence. The per-device <code>boot</code> elements cannot be
863
used together with general boot elements in
864
<a href="#elementsOSBIOS">BIOS bootloader</a> section.
865
<span class="since">Since 0.8.8</span>
712
866
</dd><dt><code>encryption</code></dt><dd>If present, specifies how the volume is encrypted. See
713
867
the <a href="formatstorageencryption.html">Storage Encryption</a> page
714
868
for more information.
718
872
</dd><dt><code>serial</code></dt><dd>If present, this specify serial number of virtual hard drive.
719
873
For example, it may look as <code><serial>WD-WMAP9A966149</serial></code>.
720
874
<span class="since">Since 0.7.1</span>
875
</dd><dt><code>host</code></dt><dd>The <code>host</code> element has two attributes "name" and "port",
876
which specify the hostname and the port number. The meaning of this
877
element and the number of the elements depend on the protocol attribute.
878
<table class="top_table"><tr><th> Protocol </th><th> Meaning </th><th> Number of hosts </th></tr><tr><td> nbd </td><td> a server running nbd-server </td><td> only one </td></tr><tr><td> rbd </td><td> monitor servers of RBD </td><td> one or more </td></tr><tr><td> sheepdog </td><td> one of the sheepdog servers (default is localhost:7000) </td><td> zero or one </td></tr></table></dd><dt><code>address</code></dt><dd>If present, the <code>address</code> element ties the disk
879
to a given slot of a controller (the
880
actual <code><controller></code> device can often be
881
inferred by libvirt, although it can
882
be <a href="#elementsControllers">explicitly specified</a>).
883
The <code>type</code> attribute is mandatory, and is typically
884
"pci" or "drive". For a "pci" controller, additional
885
attributes for <code>bus</code>, <code>slot</code>,
886
and <code>function</code> must be present, as well as an
887
optional <code>domain</code>. For a "drive" controller,
888
additional attributes <code>controller</code>, <code>bus</code>,
889
and <code>unit</code> are available, each defaulting to 0.
892
<a name="elementsControllers" id="elementsControllers">Controllers</a>
895
Many devices that have an <code><address></code>
896
sub-element are designed to work with a controller to manage
897
related devices. Normally, libvirt can automatically infer such
898
controllers without requiring explicit XML markup, but sometimes
899
it is necessary to provide an explicit controller element.
904
<controller type='ide' index='0'/>
905
<controller type='virtio-serial' index='0' ports='16' vectors='4'/>
906
<controller type='virtio-serial' index='1'>
907
<address type='pci' domain='0x0000' bus='0x00' slot='0x0a' function='0x0'/>
913
Each controller has a mandatory attribute <code>type</code>,
914
which must be one of "ide", "fdc", "scsi", "sata", "ccid", or
915
"virtio-serial", and a mandatory attribute <code>index</code>
916
which is the decimal integer describing in which order the bus
917
controller is encountered (for use in <code>controller</code>
918
attributes of <code><address></code> elements). The
919
"virtio-serial" controller has two additional optional
920
attributes <code>ports</code> and <code>vectors</code>, which
921
control how many devices can be connected through the
922
controller. A "scsi" controller has an optional
923
attribute <code>model</code>, which is one of "auto",
924
"buslogic", "lsilogic", "lsias1068", or "vmpvscsi".
927
For controllers that are themselves devices on a PCI or USB bus,
928
an optional sub-element <code><address></code> can specify
929
the exact relationship of the controller to its master bus, with
930
semantics like any other device's <code>address</code>
723
934
<a name="elementsUSB" id="elementsUSB">USB and PCI devices</a>
776
994
PCI domain, with hexadecimal values 0 to ffff, but it is currently
777
995
not used by qemu.</dd></dl>
997
<a name="elementsSmartcard" id="elementsSmartcard">Smartcard devices</a>
1000
A virtual smartcard device can be supplied to the guest via the
1001
<code>smartcard</code> element. A USB smartcard reader device on
1002
the host cannot be used on a guest with simple device
1003
passthrough, since it will then not be available on the host,
1004
possibly locking the host computer when it is "removed".
1005
Therefore, some hypervisors provide a specialized virtual device
1006
that can present a smartcard interface to the guest, with
1007
several modes for describing how credentials are obtained from
1008
the host or even a from a channel created to a third-party
1009
smartcard provider. <span class="since">Since 0.8.8</span>
1014
<smartcard mode='host'/>
1015
<smartcard mode='host-certificates'>
1016
<certificate>cert1</certificate>
1017
<certificate>cert2</certificate>
1018
<certificate>cert3</certificate>
1019
<database>/etc/pki/nssdb/</database>
1021
<smartcard mode='passthrough' type='tcp'>
1022
<source mode='bind' host='127.0.0.1' service='2001'/>
1023
<protocol type='raw'/>
1024
<address type='ccid' controller='0' slot='0'/>
1026
<smartcard mode='passthrough' type='spicevmc'/>
1031
The <code><smartcard></code> element has a mandatory
1032
attribute <code>mode</code>. The following modes are supported;
1033
in each mode, the guest sees a device on its USB bus that
1034
behaves like a physical USB CCID (Chip/Smart Card Interface
1037
<dl><dt><code>mode='host'</code></dt><dd>The simplest operation, where the hypervisor relays all
1038
requests from the guest into direct access to the host's
1039
smartcard via NSS. No other attributes or sub-elements are
1040
required. See below about the use of an
1041
optional <code><address></code> sub-element.</dd><dt><code>mode='host-certificates'</code></dt><dd>Rather than requiring a smartcard to be plugged into the
1042
host, it is possible to provide three NSS certificate names
1043
residing in a database on the host. These certificates can be
1044
generated via the command <code>certutil -d /etc/pki/nssdb -x -t
1045
CT,CT,CT -S -s CN=cert1 -n cert1</code>, and the resulting three
1046
certificate names must be supplied as the content of each of
1047
three <code><certificate></code> sub-elements. An
1048
additional sub-element <code><database></code> can specify
1049
the absolute path to an alternate directory (matching
1050
the <code>-d</code> option of the <code>certutil</code> command
1051
when creating the certificates); if not present, it defaults to
1052
/etc/pki/nssdb.</dd><dt><code>mode='passthrough'</code></dt><dd>Rather than having the hypervisor directly communicate with
1053
the host, it is possible to tunnel all requests through a
1054
secondary character device to a third-party provider (which may
1055
in turn be talking to a smartcard or using three certificate
1056
files). In this mode of operation, an additional
1057
attribute <code>type</code> is required, matching one of the
1058
supported <a href="#elementsConsole">serial device</a> types, to
1059
describe the host side of the tunnel; <code>type='tcp'</code>
1060
or <code>type='spicevmc'</code> (which uses the smartcard
1061
channel of a <a href="#elementsGraphics">SPICE graphics
1062
device</a>) are typical. Further sub-elements, such
1063
as <code><source></code>, may be required according to the
1064
given type, although a <code><target></code> sub-element
1065
is not required (since the consumer of the character device is
1066
the hypervisor itself, rather than a device visible in the
1069
Each mode supports an optional
1070
sub-element <code><address></code>, which fine-tunes the
1071
correlation between the smartcard and a ccid bus controller.
1072
If present, the element must have an attribute
1073
of <code>type='ccid'</code> as well as a <code>bus</code>
1074
attribute listing the index of the bus that the smartcard
1075
utilizes. An optional <code>slot</code> attribute lists which
1076
slot within the bus. For now, qemu only supports at most one
1077
smartcard, with an address of bus=0 slot=0.
779
1080
<a name="elementsNICS" id="elementsNICS">Network interfaces</a>
1091
1431
The <code>listen</code> attribute is an IP address for the server to
1092
1432
listen on. The <code>passwd</code> attribute provides a VNC password
1093
1433
in clear text. The <code>keymap</code> attribute specifies the keymap
1434
to use. It is possible to set a limit on the validity of the password
1435
be giving an timestamp <code>passwdValidTo='2010-04-09T15:51:00'</code>
1436
assumed to be in UTC. NB, this may not be supported by all hypervisors.<br /><br />
1437
Rather than using listen/port, QEMU supports a <code>socket</code>
1438
attribute for listening on a unix domain socket path.
1439
<span class="since">Since 0.8.8</span>
1440
</dd><dt><code>"spice"</code></dt><dd>
1442
Starts a SPICE server. The <code>port</code> attribute specifies the TCP
1443
port number (with -1 as legacy syntax indicating that it should be
1444
auto-allocated), while <code>tlsPort</code> gives an alternative
1445
secure port number. The <code>autoport</code> attribute is the new
1446
preferred syntax for indicating autoallocation of both port numbers.
1447
The <code>listen</code> attribute is an IP address for the server to
1448
listen on. The <code>passwd</code> attribute provides a SPICE password
1449
in clear text. The <code>keymap</code> attribute specifies the keymap
1450
to use. It is possible to set a limit on the validity of the password
1451
be giving an timestamp <code>passwdValidTo='2010-04-09T15:51:00'</code>
1452
assumed to be in UTC. NB, this may not be supported by all hypervisors.
1455
When SPICE has both a normal and TLS secured TCP port configured, it
1456
can be desirable to restrict what channels can be run on each port.
1457
This is achieved by adding one or more <channel> elements inside
1458
the main <graphics> element. Valid channel names include
1459
<code>main</code>, <code>display</code>, <code>inputs</code>,
1460
<code>cursor</code>, <code>playback</code>, <code>record</code>;
1461
and <span class="since">since 0.8.8</span>: <code>smartcard</code>.
1464
<graphics type='spice' port='-1' tlsPort='-1' autoport='yes'>
1465
<channel name='main' mode='secure'/>
1466
<channel name='record' mode='insecure'/>
1467
</graphics></pre>
1095
1468
</dd><dt><code>"rdp"</code></dt><dd>
1096
1469
Starts a RDP server. The <code>port</code> attribute
1097
1470
specifies the TCP port number (with -1 as legacy syntax indicating
1284
1671
forwarded to the channel device on the host. The <code>target</code>
1285
1672
element must have <code>address</code> and <code>port</code> attributes.
1286
1673
<span class="since">Since 0.7.3</span></dd><dt><code>virtio</code></dt><dd>Paravirtualized virtio channel. Channel is exposed in the guest under
1287
/dev/vport*, and if the optional element<code>name</code> is specified,
1674
/dev/vport*, and if the optional element <code>name</code> is specified,
1288
1675
/dev/virtio-ports/$name (for more info, please see
1289
<a href="http://fedoraproject.org/wiki/Features/VirtioSerial">http://fedoraproject.org/wiki/Features/VirtioSerial</a>)
1290
<span class="since">Since 0.7.7</span></dd></dl>
1676
<a href="http://fedoraproject.org/wiki/Features/VirtioSerial">http://fedoraproject.org/wiki/Features/VirtioSerial</a>). The
1677
optional element <code>address</code> can tie the channel to a
1678
particular <code>type='virtio-serial'</code> controller.
1679
<span class="since">Since 0.7.7</span></dd><dt><code>spicevmc</code></dt><dd>Paravirtualized SPICE channel. The domain must also have a
1680
SPICE server as a <a href="#elementsGraphics">graphics
1681
device</a>, at which point the host piggy-backs messages
1682
across the <code>main</code> channel. The <code>target</code>
1683
element must be present, with
1684
attribute <code>type='virtio'</code>; an optional
1685
attribute <code>name</code> controls how the guest will have
1686
access to the channel, and defaults
1687
to <code>name='com.redhat.spice.0'</code>. The
1688
optional <code>address</code> element can tie the channel to a
1689
particular <code>type='virtio-serial'</code> controller.
1690
<span class="since">Since 0.8.8</span></dd></dl>
1292
1692
<a name="elementsCharHostInterface" id="elementsCharHostInterface">Host interface</a>