docs/drvqemu.html

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <!--
   5         This file is autogenerated from drvqemu.html.in
   6         Do not edit this file. Changes will be lost.
   7       -->
   8   <head>
   9     <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
  10     <link rel="stylesheet" type="text/css" href="main.css" />
  11     <link rel="SHORTCUT ICON" href="32favicon.png" />
  12     <title>libvirt: KVM/QEMU hypervisor driver</title>
  13     <meta name="description" content="libvirt, virtualization, virtualization API" />
  14   </head>
  15   <body>
  16     <div id="header">
  17       <div id="headerLogo"></div>
  18       <div id="headerSearch">
  19         <form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><div>
  20             <input id="query" name="query" type="text" size="12" value="" />
  21             <input id="submit" name="submit" type="submit" value="Search" />
  22           </div></form>
  23       </div>
  24     </div>
  25     <div id="body">
  26       <div id="menu">
  27         <ul class="l0"><li>
  28             <div>
  29               <a title="Front page of the libvirt website" class="inactive" href="index.html">Home</a>
  30             </div>
  31           </li><li>
  32             <div>
  33               <a title="Details of new features and bugs fixed in each release" class="inactive" href="news.html">News</a>
  34             </div>
  35           </li><li>
  36             <div>
  37               <a title="Applications known to use libvirt" class="inactive" href="apps.html">Applications</a>
  38             </div>
  39           </li><li>
  40             <div>
  41               <a title="Get the latest source releases, binary builds and get access to the source repository" class="inactive" href="downloads.html">Downloads</a>
  42             </div>
  43           </li><li>
  44             <div>
  45               <a title="Information for users, administrators and developers" class="active" href="docs.html">Documentation</a>
  46               <ul class="l1"><li>
  47                   <div>
  48                     <a title="How to compile libvirt" class="inactive" href="compiling.html">Compiling</a>
  49                   </div>
  50                 </li><li>
  51                   <div>
  52                     <a title="Information about deploying and using libvirt" class="inactive" href="deployment.html">Deployment</a>
  53                   </div>
  54                 </li><li>
  55                   <div>
  56                     <a title="Overview of the logical subsystems in the libvirt API" class="inactive" href="intro.html">Architecture</a>
  57                   </div>
  58                 </li><li>
  59                   <div>
  60                     <a title="Description of the XML formats used in libvirt" class="inactive" href="format.html">XML format</a>
  61                   </div>
  62                 </li><li>
  63                   <div>
  64                     <a title="Hypervisor specific driver information" class="active" href="drivers.html">Drivers</a>
  65                     <ul class="l2"><li>
  66                         <div>
  67                           <a title="Driver the Xen hypervisor" class="inactive" href="drvxen.html">Xen</a>
  68                         </div>
  69                       </li><li>
  70                         <div>
  71                           <span class="active">QEMU / KVM</span>
  72                         </div>
  73                       </li><li>
  74                         <div>
  75                           <a title="Driver for the Linux native container API" class="inactive" href="drvlxc.html">Linux Container</a>
  76                         </div>
  77                       </li><li>
  78                         <div>
  79                           <a title="Pseudo-driver simulating APIs in memory for test suites" class="inactive" href="drvtest.html">Test</a>
  80                         </div>
  81                       </li><li>
  82                         <div>
  83                           <a title="Driver providing secure remote to the libvirt APIs" class="inactive" href="drvremote.html">Remote</a>
  84                         </div>
  85                       </li><li>
  86                         <div>
  87                           <a title="Driver for the OpenVZ container technology" class="inactive" href="drvopenvz.html">OpenVZ</a>
  88                         </div>
  89                       </li><li>
  90                         <div>
  91                           <a title="Driver for the User Mode Linux technology" class="inactive" href="drvuml.html">UML</a>
  92                         </div>
  93                       </li><li>
  94                         <div>
  95                           <a title="Driver for the storage management APIs" class="inactive" href="storage.html">Storage</a>
  96                         </div>
  97                       </li><li>
  98                         <div>
  99                           <a title="Driver for VirtualBox" class="inactive" href="drvvbox.html">VirtualBox</a>
 100                         </div>
 101                       </li><li>
 102                         <div>
 103                           <a title="Driver for VMware ESX" class="inactive" href="drvesx.html">VMware ESX</a>
 104                         </div>
 105                       </li><li>
 106                         <div>
 107                           <a title="Driver for VMware Workstation / Player" class="inactive" href="drvvmware.html">VMware Workstation / Player</a>
 108                         </div>
 109                       </li><li>
 110                         <div>
 111                           <a title="Driver for Microsoft Hyper-V" class="inactive" href="drvhyperv.html">Microsoft Hyper-V</a>
 112                         </div>
 113                       </li><li>
 114                         <div>
 115                           <a title="Driver for IBM PowerVM" class="inactive" href="drvphyp.html">IBM PowerVM</a>
 116                         </div>
 117                       </li><li>
 118                         <div>
 119                           <a title="Driver for Parallels Cloud Server" class="inactive" href="drvparallels.html">Parallels</a>
 120                         </div>
 121                       </li><li>
 122                         <div>
 123                           <a title="Driver for bhyve" class="inactive" href="drvbhyve.html">Bhyve</a>
 124                         </div>
 125                       </li></ul>
 126                   </div>
 127                 </li><li>
 128                   <div>
 129                     <a title="Reference manual for the C public API" class="inactive" href="html/index.html">API reference</a>
 130                   </div>
 131                 </li><li>
 132                   <div>
 133                     <a title="Bindings of the libvirt API for other languages" class="inactive" href="bindings.html">Language bindings</a>
 134                   </div>
 135                 </li><li>
 136                   <div>
 137                     <a title="Working on the internals of libvirt API, driver and daemon code" class="inactive" href="internals.html">Internals</a>
 138                   </div>
 139                 </li><li>
 140                   <div>
 141                     <a title="A guide and reference for developing with libvirt" class="inactive" href="devguide.html">Development Guide</a>
 142                   </div>
 143                 </li><li>
 144                   <div>
 145                     <a title="Command reference for virsh" class="inactive" href="virshcmdref.html">Virsh Commands</a>
 146                   </div>
 147                 </li><li>
 148                   <div>
 149                     <a title="Project governance and code of conduct" class="inactive" href="governance.html">Governance</a>
 150                   </div>
 151                 </li></ul>
 152             </div>
 153           </li><li>
 154             <div>
 155               <a title="User contributed content" class="inactive" href="http://wiki.libvirt.org">Wiki</a>
 156             </div>
 157           </li><li>
 158             <div>
 159               <a title="Frequently asked questions" class="inactive" href="http://wiki.libvirt.org/page/FAQ">FAQ</a>
 160             </div>
 161           </li><li>
 162             <div>
 163               <a title="How and where to report bugs and request features" class="inactive" href="bugs.html">Bug reports</a>
 164             </div>
 165           </li><li>
 166             <div>
 167               <a title="How to contact the developers via email and IRC" class="inactive" href="contact.html">Contact</a>
 168             </div>
 169           </li><li>
 170             <div>
 171               <a title="Available test suites for libvirt" class="inactive" href="testsuites.html">Test suites</a>
 172             </div>
 173           </li><li>
 174             <div>
 175               <a title="Miscellaneous links of interest related to libvirt" class="inactive" href="relatedlinks.html">Related Links</a>
 176             </div>
 177           </li><li>
 178             <div>
 179               <a title="Overview of all content on the website" class="inactive" href="sitemap.html">Sitemap</a>
 180             </div>
 181           </li></ul>
 182       </div>
 183       <div id="content">
 184         <h1>KVM/QEMU hypervisor driver</h1>
 185         <ul><li>
 186             <a href="#project">Project Links</a>
 187           </li><li>
 188             <a href="#prereq">Deployment pre-requisites</a>
 189           </li><li>
 190             <a href="#uris">Connections to QEMU driver</a>
 191           </li><li>
 192             <a href="#security">Driver security architecture</a>
 193             <ul><li>
 194                 <a href="#securitydriver">Driver instances</a>
 195               </li><li>
 196                 <a href="#securitydac">POSIX users/groups</a>
 197               </li><li>
 198                 <a href="#securitycap">Linux process capabilities</a>
 199               </li><li>
 200                 <a href="#securityselinux">SELinux basic confinement</a>
 201               </li><li>
 202                 <a href="#securitysvirt">SELinux sVirt confinement</a>
 203               </li><li>
 204                 <a href="#securitysvirtaa">AppArmor sVirt confinement</a>
 205               </li><li>
 206                 <a href="#securityacl">Cgroups device ACLs</a>
 207               </li></ul>
 208           </li><li>
 209             <a href="#imex">Import and export of libvirt domain XML configs</a>
 210             <ul><li>
 211                 <a href="#xmlimport">Converting from QEMU args to domain XML</a>
 212               </li><li>
 213                 <a href="#xmlexport">Converting from domain XML to QEMU args</a>
 214               </li></ul>
 215           </li><li>
 216             <a href="#qemucommand">Pass-through of arbitrary qemu
 217     commands</a>
 218           </li><li>
 219             <a href="#xmlconfig">Example domain XML config</a>
 220           </li></ul>
 221         <p>
 222       The libvirt KVM/QEMU driver can manage any QEMU emulator from
 223       version 0.8.1 or later. It can also manage Xenner, which
 224       provides the same QEMU command line syntax and monitor
 225       interaction.
 226     </p>
 227         <h2>
 228           <a name="project" shape="rect" id="project">Project Links</a>
 229           <a class="headerlink" href="#project" title="Permalink to this headline">¶</a>
 230         </h2>
 231         <ul><li>
 232         The <a href="http://www.linux-kvm.org/" shape="rect">KVM</a> Linux
 233         hypervisor
 234       </li><li>
 235         The <a href="http://wiki.qemu.org/Index.html" shape="rect">QEMU</a> emulator
 236       </li></ul>
 237         <h2>
 238           <a name="prereq" shape="rect" id="prereq">Deployment pre-requisites</a>
 239           <a class="headerlink" href="#prereq" title="Permalink to this headline">¶</a>
 240         </h2>
 241         <ul><li>
 242         <strong>QEMU emulators</strong>: The driver will probe <code>/usr/bin</code>
 243         for the presence of <code>qemu</code>, <code>qemu-system-x86_64</code>,
 244         <code>qemu-system-microblaze</code>,
 245         <code>qemu-system-microblazeel</code>,
 246         <code>qemu-system-mips</code>,<code>qemu-system-mipsel</code>,
 247         <code>qemu-system-sparc</code>,<code>qemu-system-ppc</code>. The results
 248         of this can be seen from the capabilities XML output.
 249       </li><li>
 250         <strong>KVM hypervisor</strong>: The driver will probe <code>/usr/bin</code>
 251         for the presence of <code>qemu-kvm</code> and <code>/dev/kvm</code> device
 252         node. If both are found, then KVM fullyvirtualized, hardware accelerated
 253         guests will be available.
 254       </li><li>
 255         <strong>Xenner hypervisor</strong>: The driver will probe <code>/usr/bin</code>
 256         for the presence of <code>xenner</code> and <code>/dev/kvm</code> device
 257         node. If both are found, then Xen paravirtualized guests can be run using
 258         the KVM hardware acceleration.
 259       </li></ul>
 260         <h2>
 261           <a name="uris" shape="rect" id="uris">Connections to QEMU driver</a>
 262           <a class="headerlink" href="#uris" title="Permalink to this headline">¶</a>
 263         </h2>
 264         <p>
 265     The libvirt QEMU driver is a multi-instance driver, providing a single
 266     system wide privileged driver (the "system" instance), and per-user
 267     unprivileged drivers (the "session" instance). The URI driver protocol
 268     is "qemu". Some example connection URIs for the libvirt driver are:
 269     </p>
 270         <pre xml:space="preserve">
 271 qemu:///session                      (local access to per-user instance)
 272 qemu+unix:///session                 (local access to per-user instance)
 273
 274 qemu:///system                       (local access to system instance)
 275 qemu+unix:///system                  (local access to system instance)
 276 qemu://example.com/system            (remote access, TLS/x509)
 277 qemu+tcp://example.com/system        (remote access, SASl/Kerberos)
 278 qemu+ssh://root@example.com/system   (remote access, SSH tunnelled)
 279 </pre>
 280         <h2>
 281           <a name="security" shape="rect" id="security">Driver security architecture</a>
 282           <a class="headerlink" href="#security" title="Permalink to this headline">¶</a>
 283         </h2>
 284         <p>
 285       There are multiple layers to security in the QEMU driver, allowing for
 286       flexibility in the use of QEMU based virtual machines.
 287     </p>
 288         <h3>
 289           <a name="securitydriver" shape="rect" id="securitydriver">Driver instances</a>
 290           <a class="headerlink" href="#securitydriver" title="Permalink to this headline">¶</a>
 291         </h3>
 292         <p>
 293       As explained above there are two ways to access the QEMU driver
 294       in libvirt. The "qemu:///session" family of URIs connect to a
 295       libvirtd instance running as the same user/group ID as the client
 296       application. Thus the QEMU instances spawned from this driver will
 297       share the same privileges as the client application. The intended
 298       use case for this driver is desktop virtualization, with virtual
 299       machines storing their disk images in the user's home directory and
 300       being managed from the local desktop login session.
 301     </p>
 302         <p>
 303       The "qemu:///system" family of URIs connect to a
 304       libvirtd instance running as the privileged system account 'root'.
 305       Thus the QEMU instances spawned from this driver may have much
 306       higher privileges than the client application managing them.
 307       The intended use case for this driver is server virtualization,
 308       where the virtual machines may need to be connected to host
 309       resources (block, PCI, USB, network devices) whose access requires
 310       elevated privileges.
 311     </p>
 312         <h3>
 313           <a name="securitydac" shape="rect" id="securitydac">POSIX users/groups</a>
 314           <a class="headerlink" href="#securitydac" title="Permalink to this headline">¶</a>
 315         </h3>
 316         <p>
 317       In the "session" instance, the POSIX users/groups model restricts QEMU
 318       virtual machines (and libvirtd in general) to only have access to resources
 319       with the same user/group ID as the client application. There is no
 320       finer level of configuration possible for the "session" instances.
 321     </p>
 322         <p>
 323       In the "system" instance, libvirt releases from 0.7.0 onwards allow
 324       control over the user/group that the QEMU virtual machines are run
 325       as. A build of libvirt with no configuration parameters set will
 326       still run QEMU processes as root:root. It is possible to change
 327       this default by using the --with-qemu-user=$USERNAME and
 328       --with-qemu-group=$GROUPNAME arguments to 'configure' during
 329       build. It is strongly recommended that vendors build with both
 330       of these arguments set to 'qemu'. Regardless of this build time
 331       default, administrators can set a per-host default setting in
 332       the <code>/etc/libvirt/qemu.conf</code> configuration file via
 333       the <code>user=$USERNAME</code> and <code>group=$GROUPNAME</code>
 334       parameters. When a non-root user or group is configured, the
 335       libvirt QEMU driver will change uid/gid to match immediately
 336       before executing the QEMU binary for a virtual machine.
 337     </p>
 338         <p>
 339       If QEMU virtual machines from the "system" instance are being
 340       run as non-root, there will be greater restrictions on what
 341       host resources the QEMU process will be able to access. The
 342       libvirtd daemon will attempt to manage permissions on resources
 343       to minimise the likelihood of unintentional security denials,
 344       but the administrator / application developer must be aware of
 345       some of the consequences / restrictions.
 346     </p>
 347         <ul><li>
 348         <p>
 349           The directories <code>/var/run/libvirt/qemu/</code>,
 350           <code>/var/lib/libvirt/qemu/</code> and
 351           <code>/var/cache/libvirt/qemu/</code> must all have their
 352           ownership set to match the user / group ID that QEMU
 353           guests will be run as. If the vendor has set a non-root
 354           user/group for the QEMU driver at build time, the
 355           permissions should be set automatically at install time.
 356           If a host administrator customizes user/group in
 357           <code>/etc/libvirt/qemu.conf</code>, they will need to
 358           manually set the ownership on these directories.
 359         </p>
 360       </li><li>
 361         <p>
 362           When attaching USB and PCI devices to a QEMU guest,
 363           QEMU will need to access files in <code>/dev/bus/usb</code>
 364           and <code>/sys/bus/pci/devices</code> respectively. The libvirtd daemon
 365           will automatically set the ownership on specific devices
 366           that are assigned to a guest at start time. There should
 367           not be any need for administrator changes in this respect.
 368         </p>
 369       </li><li>
 370         <p>
 371           Any files/devices used as guest disk images must be
 372           accessible to the user/group ID that QEMU guests are
 373           configured to run as. The libvirtd daemon will automatically
 374           set the ownership of the file/device path to the correct
 375           user/group ID. Applications / administrators must be aware
 376           though that the parent directory permissions may still
 377           deny access. The directories containing disk images
 378           must either have their ownership set to match the user/group
 379           configured for QEMU, or their UNIX file permissions must
 380           have the 'execute/search' bit enabled for 'others'.
 381         </p>
 382         <p>
 383           The simplest option is the latter one, of just enabling
 384           the 'execute/search' bit. For any directory to be used
 385           for storing disk images, this can be achieved by running
 386           the following command on the directory itself, and any
 387           parent directories
 388         </p>
 389 <pre xml:space="preserve">
 390 chmod o+x /path/to/directory
 391 </pre>
 392         <p>
 393           In particular note that if using the "system" instance
 394           and attempting to store disk images in a user home
 395           directory, the default permissions on $HOME are typically
 396           too restrictive to allow access.
 397         </p>
 398       </li></ul>
 399         <h3>
 400           <a name="securitycap" shape="rect" id="securitycap">Linux process capabilities</a>
 401           <a class="headerlink" href="#securitycap" title="Permalink to this headline">¶</a>
 402         </h3>
 403         <p>
 404       The libvirt QEMU driver has a build time option allowing it to use
 405       the <a href="http://people.redhat.com/sgrubb/libcap-ng/index.html" shape="rect">libcap-ng</a>
 406       library to manage process capabilities. If this build option is
 407       enabled, then the QEMU driver will use this to ensure that all
 408       process capabilities are dropped before executing a QEMU virtual
 409       machine. Process capabilities are what gives the 'root' account
 410       its high power, in particular the CAP_DAC_OVERRIDE capability
 411       is what allows a process running as 'root' to access files owned
 412       by any user.
 413     </p>
 414         <p>
 415       If the QEMU driver is configured to run virtual machines as non-root,
 416       then they will already lose all their process capabilities at time
 417       of startup. The Linux capability feature is thus aimed primarily at
 418       the scenario where the QEMU processes are running as root. In this
 419       case, before launching a QEMU virtual machine, libvirtd will use
 420       libcap-ng APIs to drop all process capabilities. It is important
 421       for administrators to note that this implies the QEMU process will
 422       <strong>only</strong> be able to access files owned by root, and
 423       not files owned by any other user.
 424     </p>
 425         <p>
 426       Thus, if a vendor / distributor has configured their libvirt package
 427       to run as 'qemu' by default, a number of changes will be required
 428       before an administrator can change a host to run guests as root.
 429       In particular it will be necessary to change ownership on the
 430       directories <code>/var/run/libvirt/qemu/</code>,
 431       <code>/var/lib/libvirt/qemu/</code> and
 432       <code>/var/cache/libvirt/qemu/</code> back to root, in addition
 433       to changing the <code>/etc/libvirt/qemu.conf</code> settings.
 434     </p>
 435         <h3>
 436           <a name="securityselinux" shape="rect" id="securityselinux">SELinux basic confinement</a>
 437           <a class="headerlink" href="#securityselinux" title="Permalink to this headline">¶</a>
 438         </h3>
 439         <p>
 440       The basic SELinux protection for QEMU virtual machines is intended to
 441       protect the host OS from a compromised virtual machine process. There
 442       is no protection between guests.
 443     </p>
 444         <p>
 445       In the basic model, all QEMU virtual machines run under the confined
 446       domain <code>root:system_r:qemu_t</code>. It is required that any
 447       disk image assigned to a QEMU virtual machine is labelled with
 448       <code>system_u:object_r:virt_image_t</code>. In a default deployment,
 449       package vendors/distributor will typically ensure that the directory
 450       <code>/var/lib/libvirt/images</code> has this label, such that any
 451       disk images created in this directory will automatically inherit the
 452       correct labelling. If attempting to use disk images in another
 453       location, the user/administrator must ensure the directory has be
 454       given this requisite label. Likewise physical block devices must
 455       be labelled <code>system_u:object_r:virt_image_t</code>.
 456     </p>
 457         <p>
 458       Not all filesystems allow for labelling of individual files. In
 459       particular NFS, VFat and NTFS have no support for labelling. In
 460       these cases administrators must use the 'context' option when
 461       mounting the filesystem to set the default label to
 462       <code>system_u:object_r:virt_image_t</code>. In the case of
 463       NFS, there is an alternative option, of enabling the <code>virt_use_nfs</code>
 464       SELinux boolean.
 465     </p>
 466         <h3>
 467           <a name="securitysvirt" shape="rect" id="securitysvirt">SELinux sVirt confinement</a>
 468           <a class="headerlink" href="#securitysvirt" title="Permalink to this headline">¶</a>
 469         </h3>
 470         <p>
 471       The SELinux sVirt protection for QEMU virtual machines builds to the
 472       basic level of protection, to also allow individual guests to be
 473       protected from each other.
 474     </p>
 475         <p>
 476       In the sVirt model, each QEMU virtual machine runs under its own
 477       confined domain, which is based on <code>system_u:system_r:svirt_t:s0</code>
 478       with a unique category appended, eg, <code>system_u:system_r:svirt_t:s0:c34,c44</code>.
 479       The rules are setup such that a domain can only access files which are
 480       labelled with the matching category level, eg
 481       <code>system_u:object_r:svirt_image_t:s0:c34,c44</code>. This prevents one
 482       QEMU process accessing any file resources that are prevent to another QEMU
 483       process.
 484     </p>
 485         <p>
 486       There are two ways of assigning labels to virtual machines under sVirt.
 487       In the default setup, if sVirt is enabled, guests will get an automatically
 488       assigned unique label each time they are booted. The libvirtd daemon will
 489       also automatically relabel exclusive access disk images to match this
 490       label.  Disks that are marked as &lt;shared&gt; will get a generic
 491       label <code>system_u:system_r:svirt_image_t:s0</code> allowing all guests
 492       read/write access them, while disks marked as &lt;readonly&gt; will
 493       get a generic label <code>system_u:system_r:svirt_content_t:s0</code>
 494       which allows all guests read-only access.
 495     </p>
 496         <p>
 497       With statically assigned labels, the application should include the
 498       desired guest and file labels in the XML at time of creating the
 499       guest with libvirt. In this scenario the application is responsible
 500       for ensuring the disk images &amp; similar resources are suitably
 501       labelled to match, libvirtd will not attempt any relabelling.
 502     </p>
 503         <p>
 504       If the sVirt security model is active, then the node capabilities
 505       XML will include its details. If a virtual machine is currently
 506       protected by the security model, then the guest XML will include
 507       its assigned labels. If enabled at compile time, the sVirt security
 508       model will always be activated if SELinux is available on the host
 509       OS. To disable sVirt, and revert to the basic level of SELinux
 510       protection (host protection only), the <code>/etc/libvirt/qemu.conf</code>
 511       file can be used to change the setting to <code>security_driver="none"</code>
 512     </p>
 513         <h3>
 514           <a name="securitysvirtaa" shape="rect" id="securitysvirtaa">AppArmor sVirt confinement</a>
 515           <a class="headerlink" href="#securitysvirtaa" title="Permalink to this headline">¶</a>
 516         </h3>
 517         <p>
 518       When using basic AppArmor protection for the libvirtd daemon and
 519       QEMU virtual machines, the intention is to protect the host OS
 520       from a compromised virtual machine process. There is no protection
 521       between guests.
 522     </p>
 523         <p>
 524       The AppArmor sVirt protection for QEMU virtual machines builds on
 525       this basic level of protection, to also allow individual guests to
 526       be protected from each other.
 527     </p>
 528         <p>
 529       In the sVirt model, if a profile is loaded for the libvirtd daemon,
 530       then each <code>qemu:///system</code> QEMU virtual machine will have
 531       a profile created for it when the virtual machine is started if one
 532       does not already exist. This generated profile uses a profile name
 533       based on the UUID of the QEMU virtual machine and contains rules
 534       allowing access to only the files it needs to run, such as its disks,
 535       pid file and log files. Just before the QEMU virtual machine is
 536       started, the libvirtd daemon will change into this unique profile,
 537       preventing the QEMU process from accessing any file resources that
 538       are present in another QEMU process or the host machine.
 539     </p>
 540         <p>
 541       The AppArmor sVirt implementation is flexible in that it allows an
 542       administrator to customize the template file in
 543       <code>/etc/apparmor.d/libvirt/TEMPLATE</code> for site-specific
 544       access for all newly created QEMU virtual machines. Also, when a new
 545       profile is generated, two files are created:
 546       <code>/etc/apparmor.d/libvirt/libvirt-&lt;uuid&gt;</code> and
 547       <code>/etc/apparmor.d/libvirt/libvirt-&lt;uuid&gt;.files</code>. The
 548       former can be fine-tuned by the administrator to allow custom access
 549       for this particular QEMU virtual machine, and the latter will be
 550       updated appropriately when required file access changes, such as when
 551       a disk is added. This flexibility allows for situations such as
 552       having one virtual machine in complain mode with all others in
 553       enforce mode.
 554     </p>
 555         <p>
 556       While users can define their own AppArmor profile scheme, a typical
 557       configuration will include a profile for <code>/usr/sbin/libvirtd</code>,
 558       <code>/usr/lib/libvirt/virt-aa-helper</code> (a helper program which the
 559       libvirtd daemon uses instead of manipulating AppArmor directly), and
 560       an abstraction to be included by <code>/etc/apparmor.d/libvirt/TEMPLATE</code>
 561       (typically <code>/etc/apparmor.d/abstractions/libvirt-qemu</code>).
 562       An example profile scheme can be found in the examples/apparmor
 563       directory of the source distribution.
 564     </p>
 565         <p>
 566       If the sVirt security model is active, then the node capabilities
 567       XML will include its details. If a virtual machine is currently
 568       protected by the security model, then the guest XML will include
 569       its assigned profile name. If enabled at compile time, the sVirt
 570       security model will be activated if AppArmor is available on the host
 571       OS and a profile for the libvirtd daemon is loaded when libvirtd is
 572       started. To disable sVirt, and revert to the basic level of AppArmor
 573       protection (host protection only), the <code>/etc/libvirt/qemu.conf</code>
 574       file can be used to change the setting to <code>security_driver="none"</code>.
 575     </p>
 576         <h3>
 577           <a name="securityacl" shape="rect" id="securityacl">Cgroups device ACLs</a>
 578           <a class="headerlink" href="#securityacl" title="Permalink to this headline">¶</a>
 579         </h3>
 580         <p>
 581       Recent Linux kernels have a capability known as "cgroups" which is used
 582       for resource management. It is implemented via a number of "controllers",
 583       each controller covering a specific task/functional area. One of the
 584       available controllers is the "devices" controller, which is able to
 585       setup whitelists of block/character devices that a cgroup should be
 586       allowed to access. If the "devices" controller is mounted on a host,
 587       then libvirt will automatically create a dedicated cgroup for each
 588       QEMU virtual machine and setup the device whitelist so that the QEMU
 589       process can only access shared devices, and explicitly disks images
 590       backed by block devices.
 591     </p>
 592         <p>
 593       The list of shared devices a guest is allowed access to is
 594     </p>
 595         <pre xml:space="preserve">
 596 /dev/null, /dev/full, /dev/zero,
 597 /dev/random, /dev/urandom,
 598 /dev/ptmx, /dev/kvm, /dev/kqemu,
 599 /dev/rtc, /dev/hpet, /dev/net/tun
 600 </pre>
 601         <p>
 602       In the event of unanticipated needs arising, this can be customized
 603       via the <code>/etc/libvirt/qemu.conf</code> file.
 604       To mount the cgroups device controller, the following command
 605       should be run as root, prior to starting libvirtd
 606     </p>
 607         <pre xml:space="preserve">
 608 mkdir /dev/cgroup
 609 mount -t cgroup none /dev/cgroup -o devices
 610 </pre>
 611         <p>
 612       libvirt will then place each virtual machine in a cgroup at
 613       <code>/dev/cgroup/libvirt/qemu/$VMNAME/</code>
 614     </p>
 615         <h2>
 616           <a name="imex" shape="rect" id="imex">Import and export of libvirt domain XML configs</a>
 617           <a class="headerlink" href="#imex" title="Permalink to this headline">¶</a>
 618         </h2>
 619         <p>The QEMU driver currently supports a single native
 620       config format known as <code>qemu-argv</code>. The data for this format
 621       is expected to be a single line first a list of environment variables,
 622       then the QEMu binary name, finally followed by the QEMU command line
 623       arguments</p>
 624         <h3>
 625           <a name="xmlimport" shape="rect" id="xmlimport">Converting from QEMU args to domain XML</a>
 626           <a class="headerlink" href="#xmlimport" title="Permalink to this headline">¶</a>
 627         </h3>
 628         <p>
 629       The <code>virsh domxml-from-native</code> provides a way to
 630       convert an existing set of QEMU args into a guest description
 631       using libvirt Domain XML that can then be used by libvirt.
 632       Please note that this command is intended to be used to convert
 633       existing qemu guests previously started from the command line to
 634       be managed through libvirt.  It should not be used a method of
 635       creating new guests from scratch.  New guests should be created
 636       using an application calling the libvirt APIs (see
 637       the <a href="apps.html" shape="rect">libvirt applications page</a> for some
 638       examples) or by manually crafting XML to pass to virsh.
 639     </p>
 640         <pre xml:space="preserve">$ cat &gt; demo.args &lt;&lt;EOF
 641 LC_ALL=C PATH=/bin HOME=/home/test USER=test \
 642 LOGNAME=test /usr/bin/qemu -S -M pc -m 214 -smp 1 \
 643 -nographic -monitor pty -no-acpi -boot c -hda \
 644 /dev/HostVG/QEMUGuest1 -net none -serial none \
 645 -parallel none -usb
 646 EOF
 647
 648 $ virsh domxml-from-native qemu-argv demo.args
 649 &lt;domain type='qemu'&gt;
 650   &lt;uuid&gt;00000000-0000-0000-0000-000000000000&lt;/uuid&gt;
 651   &lt;memory&gt;219136&lt;/memory&gt;
 652   &lt;currentMemory&gt;219136&lt;/currentMemory&gt;
 653   &lt;vcpu&gt;1&lt;/vcpu&gt;
 654   &lt;os&gt;
 655     &lt;type arch='i686' machine='pc'&gt;hvm&lt;/type&gt;
 656     &lt;boot dev='hd'/&gt;
 657   &lt;/os&gt;
 658   &lt;clock offset='utc'/&gt;
 659   &lt;on_poweroff&gt;destroy&lt;/on_poweroff&gt;
 660   &lt;on_reboot&gt;restart&lt;/on_reboot&gt;
 661   &lt;on_crash&gt;destroy&lt;/on_crash&gt;
 662   &lt;devices&gt;
 663     &lt;emulator&gt;/usr/bin/qemu&lt;/emulator&gt;
 664     &lt;disk type='block' device='disk'&gt;
 665       &lt;source dev='/dev/HostVG/QEMUGuest1'/&gt;
 666       &lt;target dev='hda' bus='ide'/&gt;
 667     &lt;/disk&gt;
 668   &lt;/devices&gt;
 669 &lt;/domain&gt;
 670 </pre>
 671         <p>NB, don't include the literal \ in the args, put everything on one line</p>
 672         <h3>
 673           <a name="xmlexport" shape="rect" id="xmlexport">Converting from domain XML to QEMU args</a>
 674           <a class="headerlink" href="#xmlexport" title="Permalink to this headline">¶</a>
 675         </h3>
 676         <p>
 677       The <code>virsh domxml-to-native</code> provides a way to convert a
 678       guest description using libvirt Domain XML, into a set of QEMU args
 679       that can be run manually.
 680     </p>
 681         <pre xml:space="preserve">$ cat &gt; demo.xml &lt;&lt;EOF
 682 &lt;domain type='qemu'&gt;
 683   &lt;name&gt;QEMUGuest1&lt;/name&gt;
 684   &lt;uuid&gt;c7a5fdbd-edaf-9455-926a-d65c16db1809&lt;/uuid&gt;
 685   &lt;memory&gt;219200&lt;/memory&gt;
 686   &lt;currentMemory&gt;219200&lt;/currentMemory&gt;
 687   &lt;vcpu&gt;1&lt;/vcpu&gt;
 688   &lt;os&gt;
 689     &lt;type arch='i686' machine='pc'&gt;hvm&lt;/type&gt;
 690     &lt;boot dev='hd'/&gt;
 691   &lt;/os&gt;
 692   &lt;clock offset='utc'/&gt;
 693   &lt;on_poweroff&gt;destroy&lt;/on_poweroff&gt;
 694   &lt;on_reboot&gt;restart&lt;/on_reboot&gt;
 695   &lt;on_crash&gt;destroy&lt;/on_crash&gt;
 696   &lt;devices&gt;
 697     &lt;emulator&gt;/usr/bin/qemu&lt;/emulator&gt;
 698     &lt;disk type='block' device='disk'&gt;
 699       &lt;source dev='/dev/HostVG/QEMUGuest1'/&gt;
 700       &lt;target dev='hda' bus='ide'/&gt;
 701     &lt;/disk&gt;
 702   &lt;/devices&gt;
 703 &lt;/domain&gt;
 704 EOF
 705
 706 $ virsh domxml-to-native qemu-argv demo.xml
 707   LC_ALL=C PATH=/usr/bin:/bin HOME=/home/test \
 708   USER=test LOGNAME=test /usr/bin/qemu -S -M pc \
 709   -no-kqemu -m 214 -smp 1 -name QEMUGuest1 -nographic \
 710   -monitor pty -no-acpi -boot c -drive \
 711   file=/dev/HostVG/QEMUGuest1,if=ide,index=0 -net none \
 712   -serial none -parallel none -usb
 713 </pre>
 714         <h2>
 715           <a name="qemucommand" shape="rect" id="qemucommand">Pass-through of arbitrary qemu
 716     commands</a>
 717           <a class="headerlink" href="#qemucommand" title="Permalink to this headline">¶</a>
 718         </h2>
 719         <p>Libvirt provides an XML namespace and an optional
 720       library <code>libvirt-qemu.so</code> for dealing specifically
 721       with qemu.  When used correctly, these extensions allow testing
 722       specific qemu features that have not yet been ported to the
 723       generic libvirt XML and API interfaces.  However, they
 724       are <b>unsupported</b>, in that the library is not guaranteed to
 725       have a stable API, abusing the library or XML may result in
 726       inconsistent state the crashes libvirtd, and upgrading either
 727       qemu-kvm or libvirtd may break behavior of a domain that was
 728       relying on a qemu-specific pass-through.  If you find yourself
 729       needing to use them to access a particular qemu feature, then
 730       please post an RFE to the libvirt mailing list to get that
 731       feature incorporated into the stable libvirt XML and API
 732       interfaces.
 733     </p>
 734         <p>The library provides two
 735       API: <code>virDomainQemuMonitorCommand</code>, for sending an
 736       arbitrary monitor command (in either HMP or QMP format) to a
 737       qemu guest (<span class="since">Since 0.8.3</span>),
 738       and <code>virDomainQemuAttach</code>, for registering a qemu
 739       domain that was manually started so that it can then be managed
 740       by libvirtd (<span class="since">Since 0.9.4</span>).
 741     </p>
 742         <p>Additionally, the following XML additions allow fine-tuning of
 743       the command line given to qemu when starting a domain
 744       (<span class="since">Since 0.8.3</span>).  In order to use the
 745       XML additions, it is necessary to issue an XML namespace request
 746       (the special <code>xmlns:<i>name</i></code> attribute) that
 747       pulls in <code>http://libvirt.org/schemas/domain/qemu/1.0</code>;
 748       typically, the namespace is given the name
 749       of <code>qemu</code>.  With the namespace in place, it is then
 750       possible to add an element <code>&lt;qemu:commandline&gt;</code>
 751       under <code>driver</code>, with the following sub-elements
 752       repeated as often as needed:
 753     </p>
 754         <dl><dt><code>qemu:arg</code></dt><dd>Add an additional command-line argument to the qemu
 755           process when starting the domain, given by the value of the
 756           attribute <code>value</code>.
 757         </dd><dt><code>qemu:env</code></dt><dd>Add an additional environment variable to the qemu
 758           process when starting the domain, given with the name-value
 759           pair recorded in the attributes <code>name</code>
 760           and optional <code>value</code>.</dd></dl>
 761         <p>Example:</p>
 762         <pre xml:space="preserve">
 763 &lt;domain type='qemu' xmlns:qemu='http://libvirt.org/schemas/domain/qemu/1.0'&gt;
 764   &lt;name&gt;QEmu-fedora-i686&lt;/name&gt;
 765   &lt;memory&gt;219200&lt;/memory&gt;
 766   &lt;os&gt;
 767     &lt;type arch='i686' machine='pc'&gt;hvm&lt;/type&gt;
 768   &lt;/os&gt;
 769   &lt;devices&gt;
 770     &lt;emulator&gt;/usr/bin/qemu-system-x86_64&lt;/emulator&gt;
 771   &lt;/devices&gt;
 772   &lt;qemu:commandline&gt;
 773     &lt;qemu:arg value='-newarg'/&gt;
 774     &lt;qemu:env name='QEMU_ENV' value='VAL'/&gt;
 775   &lt;/qemu:commandline&gt;
 776 &lt;/domain&gt;
 777 </pre>
 778         <h2>
 779           <a name="xmlconfig" shape="rect" id="xmlconfig">Example domain XML config</a>
 780           <a class="headerlink" href="#xmlconfig" title="Permalink to this headline">¶</a>
 781         </h2>
 782         <h3>QEMU emulated guest on x86_64</h3>
 783         <pre xml:space="preserve">&lt;domain type='qemu'&gt;
 784   &lt;name&gt;QEmu-fedora-i686&lt;/name&gt;
 785   &lt;uuid&gt;c7a5fdbd-cdaf-9455-926a-d65c16db1809&lt;/uuid&gt;
 786   &lt;memory&gt;219200&lt;/memory&gt;
 787   &lt;currentMemory&gt;219200&lt;/currentMemory&gt;
 788   &lt;vcpu&gt;2&lt;/vcpu&gt;
 789   &lt;os&gt;
 790     &lt;type arch='i686' machine='pc'&gt;hvm&lt;/type&gt;
 791     &lt;boot dev='cdrom'/&gt;
 792   &lt;/os&gt;
 793   &lt;devices&gt;
 794     &lt;emulator&gt;/usr/bin/qemu-system-x86_64&lt;/emulator&gt;
 795     &lt;disk type='file' device='cdrom'&gt;
 796       &lt;source file='/home/user/boot.iso'/&gt;
 797       &lt;target dev='hdc'/&gt;
 798       &lt;readonly/&gt;
 799     &lt;/disk&gt;
 800     &lt;disk type='file' device='disk'&gt;
 801       &lt;source file='/home/user/fedora.img'/&gt;
 802       &lt;target dev='hda'/&gt;
 803     &lt;/disk&gt;
 804     &lt;interface type='network'&gt;
 805       &lt;source network='default'/&gt;
 806     &lt;/interface&gt;
 807     &lt;graphics type='vnc' port='-1'/&gt;
 808   &lt;/devices&gt;
 809 &lt;/domain&gt;</pre>
 810         <h3>KVM hardware accelerated guest on i686</h3>
 811         <pre xml:space="preserve">&lt;domain type='kvm'&gt;
 812   &lt;name&gt;demo2&lt;/name&gt;
 813   &lt;uuid&gt;4dea24b3-1d52-d8f3-2516-782e98a23fa0&lt;/uuid&gt;
 814   &lt;memory&gt;131072&lt;/memory&gt;
 815   &lt;vcpu&gt;1&lt;/vcpu&gt;
 816   &lt;os&gt;
 817     &lt;type arch="i686"&gt;hvm&lt;/type&gt;
 818   &lt;/os&gt;
 819   &lt;clock sync="localtime"/&gt;
 820   &lt;devices&gt;
 821     &lt;emulator&gt;/usr/bin/qemu-kvm&lt;/emulator&gt;
 822     &lt;disk type='file' device='disk'&gt;
 823       &lt;source file='/var/lib/libvirt/images/demo2.img'/&gt;
 824       &lt;target dev='hda'/&gt;
 825     &lt;/disk&gt;
 826     &lt;interface type='network'&gt;
 827       &lt;source network='default'/&gt;
 828       &lt;mac address='24:42:53:21:52:45'/&gt;
 829     &lt;/interface&gt;
 830     &lt;graphics type='vnc' port='-1' keymap='de'/&gt;
 831   &lt;/devices&gt;
 832 &lt;/domain&gt;</pre>
 833         <h3>Xen paravirtualized guests with hardware acceleration</h3>
 834       </div>
 835     </div>
 836     <div id="footer">
 837       <p id="sponsor">
 838             Sponsored by:<br /><a href="http://et.redhat.com/"><img src="et.png" alt="Project sponsored by Red Hat Emerging Technology" /></a></p>
 839     </div>
 840   </body>
 841 </html>