docs/drvesx.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 drvesx.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: VMware ESX 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                           <a title="Driver for QEMU, KQEMU, KVM and Xenner" class="inactive" href="drvqemu.html">QEMU / KVM</a>
  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                           <span class="active">VMware ESX</span>
 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>VMware ESX 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="#uri">Connections to the VMware ESX driver</a>
 191             <ul><li>
 192                 <a href="#uriformat">URI Format</a>
 193                 <ul><li>
 194                     <a href="#extraparams">Extra parameters</a>
 195                   </li></ul>
 196               </li><li>
 197                 <a href="#auth">Authentication</a>
 198               </li><li>
 199                 <a href="#certificates">Certificates for HTTPS</a>
 200               </li><li>
 201                 <a href="#connproblems">Connection problems</a>
 202               </li></ul>
 203           </li><li>
 204             <a href="#questions">Questions blocking tasks</a>
 205           </li><li>
 206             <a href="#xmlspecial">Specialties in the domain XML config</a>
 207             <ul><li>
 208                 <a href="#restrictions">Restrictions</a>
 209               </li><li>
 210                 <a href="#datastore">Datastore references</a>
 211               </li><li>
 212                 <a href="#macaddresses">MAC addresses</a>
 213               </li><li>
 214                 <a href="#hardware">Available hardware</a>
 215               </li></ul>
 216           </li><li>
 217             <a href="#importexport">Import and export of domain XML configs</a>
 218             <ul><li>
 219                 <a href="#xmlimport">Converting from VMware VMX config to domain XML config</a>
 220               </li><li>
 221                 <a href="#xmlexport">Converting from domain XML config to VMware VMX config</a>
 222               </li></ul>
 223           </li><li>
 224             <a href="#xmlconfig">Example domain XML configs</a>
 225           </li><li>
 226             <a href="#migration">Migration</a>
 227           </li><li>
 228             <a href="#scheduler">Scheduler configuration</a>
 229           </li><li>
 230             <a href="#tools">VMware tools</a>
 231           </li><li>
 232             <a href="#links">Links</a>
 233           </li></ul>
 234         <p>
 235         The libvirt VMware ESX driver can manage VMware ESX/ESXi 3.5/4.x/5.x and
 236         VMware GSX 2.0, also called VMware Server 2.0, and possibly later
 237         versions. <span class="since">Since 0.8.3</span> the driver can also
 238         connect to a VMware vCenter 2.5/4.x/5.x (VPX).
 239     </p>
 240         <h2>
 241           <a name="project" shape="rect" id="project">Project Links</a>
 242           <a class="headerlink" href="#project" title="Permalink to this headline">¶</a>
 243         </h2>
 244         <ul><li>
 245         The <a href="http://www.vmware.com/" shape="rect">VMware ESX and GSX</a>
 246         hypervisors
 247       </li></ul>
 248         <h2>
 249           <a name="prereq" shape="rect" id="prereq">Deployment pre-requisites</a>
 250           <a class="headerlink" href="#prereq" title="Permalink to this headline">¶</a>
 251         </h2>
 252         <p>
 253         None. Any out-of-the-box installation of VPX/ESX(i)/GSX should work. No
 254         preparations are required on the server side, no libvirtd must be
 255         installed on the ESX server. The driver uses version 2.5 of the remote,
 256         SOAP based
 257         <a href="http://www.vmware.com/support/developer/vc-sdk/visdk25pubs/ReferenceGuide/" shape="rect">
 258         VMware Virtual Infrastructure API</a> (VI API) to communicate with the
 259         ESX server, like the VMware Virtual Infrastructure Client (VI client)
 260         does. Since version 4.0 this API is called
 261         <a href="http://www.vmware.com/support/developer/vc-sdk/visdk400pubs/ReferenceGuide/" shape="rect">
 262         VMware vSphere API</a>.
 263     </p>
 264         <h2>
 265           <a name="uri" shape="rect" id="uri">Connections to the VMware ESX driver</a>
 266           <a class="headerlink" href="#uri" title="Permalink to this headline">¶</a>
 267         </h2>
 268         <p>
 269         Some example remote connection URIs for the driver are:
 270     </p>
 271         <pre xml:space="preserve">
 272 vpx://example-vcenter.com/dc1/srv1     (VPX over HTTPS, select ESX server 'srv1' in datacenter 'dc1')
 273 esx://example-esx.com                  (ESX over HTTPS)
 274 gsx://example-gsx.com                  (GSX over HTTPS)
 275 esx://example-esx.com/?transport=http  (ESX over HTTP)
 276 esx://example-esx.com/?no_verify=1     (ESX over HTTPS, but doesn't verify the server's SSL certificate)
 277 </pre>
 278         <p>
 279         <strong>Note</strong>: In contrast to other drivers, the ESX driver is
 280         a client-side-only driver. It connects to the ESX server using HTTP(S).
 281         Therefore, the <a href="remote.html" shape="rect">remote transport mechanism</a>
 282         provided by the remote driver and libvirtd will not work, and you
 283         cannot use URIs like <code>esx+ssh://example.com</code>.
 284     </p>
 285         <h3>
 286           <a name="uriformat" shape="rect" id="uriformat">URI Format</a>
 287           <a class="headerlink" href="#uriformat" title="Permalink to this headline">¶</a>
 288         </h3>
 289         <p>
 290         URIs have this general form (<code>[...]</code> marks an optional part).
 291     </p>
 292         <pre xml:space="preserve">
 293 type://[username@]hostname[:port]/[[folder/...]datacenter/[folder/...][cluster/]server][?extraparameters]
 294 </pre>
 295         <p>
 296         The <code>type://</code> is either <code>esx://</code> or
 297         <code>gsx://</code> or <code>vpx://</code> <span class="since">since 0.8.3</span>.
 298         The driver selects the default port depending on the <code>type://</code>.
 299         For <code>esx://</code> and <code>vpx://</code> the default HTTPS port
 300         is 443, for <code>gsx://</code> it is 8333.
 301         If the port parameter is given, it overrides the default port.
 302     </p>
 303         <p>
 304         A <code>vpx://</code> connection is currently restricted to a single
 305         ESX server. This might be relaxed in the future. The path part of the
 306         URI is used to specify the datacenter and the ESX server in it. If the
 307         ESX server is part of a cluster then the cluster has to be specified too.
 308     </p>
 309         <p>
 310         An example: ESX server <code>example-esx.com</code> is managed by
 311         vCenter <code>example-vcenter.com</code> and part of cluster
 312         <code>cluster1</code>. This cluster is part of datacenter <code>dc1</code>.
 313     </p>
 314         <pre xml:space="preserve">
 315 vpx://example-vcenter.com/dc1/cluster1/example-esx.com
 316 </pre>
 317         <p>
 318         Datacenters and clusters can be organized in folders, those have to be
 319         specified as well. The driver can handle folders
 320         <span class="since">since 0.9.7</span>.
 321     </p>
 322         <pre xml:space="preserve">
 323 vpx://example-vcenter.com/folder1/dc1/folder2/example-esx.com
 324 </pre>
 325         <h4>
 326           <a name="extraparams" shape="rect" id="extraparams">Extra parameters</a>
 327           <a class="headerlink" href="#extraparams" title="Permalink to this headline">¶</a>
 328         </h4>
 329         <p>
 330         Extra parameters can be added to a URI as part of the query string
 331         (the part following <code>?</code>). A single parameter is formed by a
 332         <code>name=value</code> pair. Multiple parameters are separated by
 333         <code>&amp;</code>.
 334     </p>
 335         <pre xml:space="preserve">
 336 ?<span style="color: #E50000">no_verify=1</span>&amp;<span style="color: #00B200">auto_answer=1</span>&amp;<span style="color: #0000E5">proxy=socks://example-proxy.com:23456</span>
 337 </pre>
 338         <p>
 339         The driver understands the extra parameters shown below.
 340     </p>
 341         <table class="top_table"><tr><th rowspan="1" colspan="1">Name</th><th rowspan="1" colspan="1">Values</th><th rowspan="1" colspan="1">Meaning</th></tr><tr><td rowspan="1" colspan="1">
 342                 <code>transport</code>
 343             </td><td rowspan="1" colspan="1">
 344                 <code>http</code> or <code>https</code>
 345             </td><td rowspan="1" colspan="1">
 346                 Overrides the default HTTPS transport. For <code>esx://</code>
 347                 and <code>vpx://</code> the default HTTP port is 80, for
 348                 <code>gsx://</code> it is 8222.
 349             </td></tr><tr><td rowspan="1" colspan="1">
 350                 <code>vcenter</code>
 351             </td><td rowspan="1" colspan="1">
 352                 Hostname of a VMware vCenter or <code>*</code>
 353             </td><td rowspan="1" colspan="1">
 354                 In order to perform a migration the driver needs to know the
 355                 VMware vCenter for the ESX server. If set to <code>*</code>,
 356                 the driver connects to the vCenter known to the ESX server.
 357                 This parameter in useful when connecting to an ESX server only.
 358             </td></tr><tr><td rowspan="1" colspan="1">
 359                 <code>no_verify</code>
 360             </td><td rowspan="1" colspan="1">
 361                 <code>0</code> or <code>1</code>
 362             </td><td rowspan="1" colspan="1">
 363                 If set to 1, this disables libcurl client checks of the server's
 364                 SSL certificate. The default value it 0. See the
 365                 <a href="#certificates" shape="rect">Certificates for HTTPS</a> section for
 366                 details.
 367             </td></tr><tr><td rowspan="1" colspan="1">
 368                 <code>auto_answer</code>
 369             </td><td rowspan="1" colspan="1">
 370                 <code>0</code> or <code>1</code>
 371             </td><td rowspan="1" colspan="1">
 372                 If set to 1, the driver answers all
 373                 <a href="#questions" shape="rect">questions</a> with the default answer.
 374                 If set to 0, questions are reported as errors. The default
 375                 value it 0. <span class="since">Since 0.7.5</span>.
 376             </td></tr><tr><td rowspan="1" colspan="1">
 377                 <code>proxy</code>
 378             </td><td rowspan="1" colspan="1">
 379                 <code>[type://]hostname[:port]</code>
 380             </td><td rowspan="1" colspan="1">
 381                 Allows to specify a proxy for HTTP and HTTPS communication.
 382                 <span class="since">Since 0.8.2</span>.
 383                 The optional <code>type</code> part may be one of:
 384                 <code>http</code>, <code>socks</code>, <code>socks4</code>,
 385                 <code>socks4a</code> or <code>socks5</code>. The default is
 386                 <code>http</code> and <code>socks</code> is synonymous for
 387                 <code>socks5</code>. The optional <code>port</code> allows to
 388                 override the default port 1080.
 389             </td></tr></table>
 390         <h3>
 391           <a name="auth" shape="rect" id="auth">Authentication</a>
 392           <a class="headerlink" href="#auth" title="Permalink to this headline">¶</a>
 393         </h3>
 394         <p>
 395         In order to perform any useful operation the driver needs to log into
 396         the ESX server. Therefore, only <code>virConnectOpenAuth</code> can be
 397         used to connect to an ESX server, <code>virConnectOpen</code> and
 398         <code>virConnectOpenReadOnly</code> don't work.
 399         To log into an ESX server or vCenter the driver will request
 400         credentials using the callback passed to the
 401         <code>virConnectOpenAuth</code> function. The driver passes the
 402         hostname as challenge parameter to the callback. This enables the
 403         callback to distinguish between requests for ESX server and vCenter.
 404     </p>
 405         <p>
 406         <strong>Note</strong>: During the ongoing driver development, testing
 407         is done using an unrestricted <code>root</code> account. Problems may
 408         occur if you use a restricted account. Detailed testing with restricted
 409         accounts has not been done yet.
 410     </p>
 411         <h3>
 412           <a name="certificates" shape="rect" id="certificates">Certificates for HTTPS</a>
 413           <a class="headerlink" href="#certificates" title="Permalink to this headline">¶</a>
 414         </h3>
 415         <p>
 416         By default the ESX driver uses HTTPS to communicate with an ESX server.
 417         Proper HTTPS communication requires correctly configured SSL
 418         certificates. This certificates are different from the ones libvirt
 419         uses for <a href="remote.html" shape="rect">secure communication over TLS</a> to a
 420         libvirtd one a remote server.
 421     </p>
 422         <p>
 423         By default the driver tries to verify the server's SSL certificate
 424         using the CA certificate pool installed on your client computer. With
 425         an out-of-the-box installed ESX server this won't work, because a newly
 426         installed ESX server uses auto-generated self-signed certificates.
 427         Those are singed by a CA certificate that is typically not known to your
 428         client computer and libvirt will report an error like this one:
 429     </p>
 430         <pre xml:space="preserve">
 431 error: internal error curl_easy_perform() returned an error: Peer certificate cannot be authenticated with known CA certificates (60)
 432 </pre>
 433         <p>
 434         Where are two ways to solve this problem:
 435     </p>
 436         <ul><li>
 437             Use the <code>no_verify=1</code> <a href="#extraparams" shape="rect">extra parameter</a>
 438             to disable server certificate verification.
 439         </li><li>
 440             Generate new SSL certificates signed by a CA known to your client
 441             computer and replace the original ones on your ESX server. See the
 442             section <i>Replace a Default Certificate with a CA-Signed Certificate</i>
 443             in the <a href="http://www.vmware.com/pdf/vsphere4/r40/vsp_40_esx_server_config.pdf" shape="rect">ESX Configuration Guide</a>
 444         </li></ul>
 445         <h3>
 446           <a name="connproblems" shape="rect" id="connproblems">Connection problems</a>
 447           <a class="headerlink" href="#connproblems" title="Permalink to this headline">¶</a>
 448         </h3>
 449         <p>
 450         There are also other causes for connection problems than the
 451         <a href="#certificates" shape="rect">HTTPS certificate</a> related ones.
 452     </p>
 453         <ul><li>
 454             As stated before the ESX driver doesn't need the
 455             <a href="remote.html" shape="rect">remote transport mechanism</a>
 456             provided by the remote driver and libvirtd, nor does the ESX driver
 457             support it. Therefore, using an URI including a transport in the
 458             scheme won't work. Only <a href="#uriformat" shape="rect">URIs as described</a>
 459             are supported by the ESX driver. Here's a collection of possible
 460             error messages:
 461 <pre xml:space="preserve">
 462 $ virsh -c esx+tcp://example.com/
 463 error: unable to connect to libvirtd at 'example.com': Connection refused
 464 </pre>
 465 <pre xml:space="preserve">
 466 $ virsh -c esx+tls://example.com/
 467 error: Cannot access CA certificate '/etc/pki/CA/cacert.pem': No such file or directory
 468 </pre>
 469 <pre xml:space="preserve">
 470 $ virsh -c esx+ssh://example.com/
 471 error: cannot recv data: ssh: connect to host example.com port 22: Connection refused
 472 </pre>
 473 <pre xml:space="preserve">
 474 $ virsh -c esx+ssh://example.com/
 475 error: cannot recv data: Resource temporarily unavailable
 476 </pre>
 477         </li><li>
 478             <span class="since">Since 0.7.0</span> libvirt contains the ESX
 479             driver. Earlier versions of libvirt will report a misleading error
 480             about missing certificates when you try to connect to an ESX server.
 481 <pre xml:space="preserve">
 482 $ virsh -c esx://example.com/
 483 error: Cannot access CA certificate '/etc/pki/CA/cacert.pem': No such file or directory
 484 </pre>
 485             <p>
 486                 Don't let this error message confuse you. Setting up certificates
 487                 as described on the <a href="remote.html#Remote_certificates" shape="rect">remote transport mechanism</a> page
 488                 does not help, as this is not a certificate related problem.
 489             </p>
 490             <p>
 491                 To fix this problem you need to update your libvirt to 0.7.0 or newer.
 492                 You may also see this error when you use a libvirt version that
 493                 contains the ESX driver but you or your distro disabled the ESX
 494                 driver during compilation. <span class="since">Since 0.8.3</span>
 495                 the error message has been improved in this case:
 496             </p>
 497 <pre xml:space="preserve">
 498 $ virsh -c esx://example.com/
 499 error: invalid argument in libvirt was built without the 'esx' driver
 500 </pre>
 501         </li></ul>
 502         <h2>
 503           <a name="questions" shape="rect" id="questions">Questions blocking tasks</a>
 504           <a class="headerlink" href="#questions" title="Permalink to this headline">¶</a>
 505         </h2>
 506         <p>
 507         Some methods of the VI API start tasks, for example
 508         <code>PowerOnVM_Task()</code>. Such tasks may be blocked by questions
 509         if the ESX server detects an issue with the domain that requires user
 510         interaction. The ESX driver cannot prompt the user to answer a
 511         question, libvirt doesn't have an API for something like this.
 512     </p>
 513         <p>
 514         The VI API provides the <code>AnswerVM()</code> method to
 515         programmatically answer a questions. So the driver has two options
 516         how to handle such a situation: either answer the questions with the
 517         default answer or report the question as an error and cancel the
 518         blocked task if possible. The
 519         <a href="#uriformat" shape="rect"><code>auto_answer</code></a> query parameter
 520         controls the answering behavior.
 521     </p>
 522         <h2>
 523           <a name="xmlspecial" shape="rect" id="xmlspecial">Specialties in the domain XML config</a>
 524           <a class="headerlink" href="#xmlspecial" title="Permalink to this headline">¶</a>
 525         </h2>
 526         <p>
 527         There are several specialties in the domain XML config for ESX domains.
 528     </p>
 529         <h3>
 530           <a name="restrictions" shape="rect" id="restrictions">Restrictions</a>
 531           <a class="headerlink" href="#restrictions" title="Permalink to this headline">¶</a>
 532         </h3>
 533         <p>
 534         There are some restrictions for some values of the domain XML config.
 535         The driver will complain if this restrictions are violated.
 536     </p>
 537         <ul><li>
 538             Memory size has to be a multiple of 4096
 539         </li><li>
 540             Number of virtual CPU has to be 1 or a multiple of 2
 541         </li><li>
 542             Valid MAC address prefixes are <code>00:0c:29</code> and
 543             <code>00:50:56</code>. <span class="since">Since 0.7.6</span>
 544             arbitrary <a href="#macaddresses" shape="rect">MAC addresses</a> are supported.
 545         </li></ul>
 546         <h3>
 547           <a name="datastore" shape="rect" id="datastore">Datastore references</a>
 548           <a class="headerlink" href="#datastore" title="Permalink to this headline">¶</a>
 549         </h3>
 550         <p>
 551         Storage is managed in datastores. VMware uses a special path format to
 552         reference files in a datastore. Basically, the datastore name is put
 553         into squared braces in front of the path.
 554     </p>
 555         <pre xml:space="preserve">
 556 [datastore] directory/filename
 557 </pre>
 558         <p>
 559         To define a new domain the driver converts the domain XML into a
 560         VMware VMX file and uploads it to a datastore known to the ESX server.
 561         Because multiple datastores may be known to an ESX server the driver
 562         needs to decide to which datastore the VMX file should be uploaded.
 563         The driver deduces this information from the path of the source of the
 564         first file-based harddisk listed in the domain XML.
 565     </p>
 566         <h3>
 567           <a name="macaddresses" shape="rect" id="macaddresses">MAC addresses</a>
 568           <a class="headerlink" href="#macaddresses" title="Permalink to this headline">¶</a>
 569         </h3>
 570         <p>
 571         VMware has registered two MAC address prefixes for domains:
 572         <code>00:0c:29</code> and <code>00:50:56</code>. These prefixes are
 573         split into ranges for different purposes.
 574     </p>
 575         <table class="top_table"><tr><th rowspan="1" colspan="1">Range</th><th rowspan="1" colspan="1">Purpose</th></tr><tr><td rowspan="1" colspan="1">
 576                 <code>00:0c:29:00:00:00</code> - <code>00:0c:29:ff:ff:ff</code>
 577             </td><td rowspan="1" colspan="1">
 578                 An ESX server autogenerates MAC addresses from this range if
 579                 the VMX file doesn't contain a MAC address when trying to start
 580                 a domain.
 581             </td></tr><tr><td rowspan="1" colspan="1">
 582                 <code>00:50:56:00:00:00</code> - <code>00:50:56:3f:ff:ff</code>
 583             </td><td rowspan="1" colspan="1">
 584                 MAC addresses from this range can by manually assigned by the
 585                 user in the VI client.
 586             </td></tr><tr><td rowspan="1" colspan="1">
 587                 <code>00:50:56:80:00:00</code> - <code>00:50:56:bf:ff:ff</code>
 588             </td><td rowspan="1" colspan="1">
 589                 A VI client autogenerates MAC addresses from this range for
 590                 newly defined domains.
 591             </td></tr></table>
 592         <p>
 593         The VMX files generated by the ESX driver always contain a MAC address,
 594         because libvirt generates a random one if an interface element in the
 595         domain XML file lacks a MAC address.
 596         <span class="since">Since 0.7.6</span> the ESX driver sets the prefix
 597         for generated MAC addresses to <code>00:0c:29</code>. Before 0.7.6
 598         the <code>00:50:56</code> prefix was used. Sometimes this resulted in
 599         the generation of out-of-range MAC address that were rejected by the
 600         ESX server.
 601     </p>
 602         <p>
 603         Also <span class="since">since 0.7.6</span> every MAC address outside
 604         this ranges can be used. For such MAC addresses the ESX server-side
 605         check is disabled in the VMX file to stop the ESX server from rejecting
 606         out-of-predefined-range MAC addresses.
 607     </p>
 608         <pre xml:space="preserve">
 609 ethernet0.checkMACAddress = "false"
 610 </pre>
 611         <h3>
 612           <a name="hardware" shape="rect" id="hardware">Available hardware</a>
 613           <a class="headerlink" href="#hardware" title="Permalink to this headline">¶</a>
 614         </h3>
 615         <p>
 616         VMware ESX supports different models of SCSI controllers and network
 617         cards.
 618     </p>
 619         <h4>SCSI controller models</h4>
 620         <dl><dt><code>auto</code></dt><dd>
 621             This isn't a actual controller model. If specified the ESX driver
 622             tries to detect the SCSI controller model referenced in the
 623             <code>.vmdk</code> file and use it. Autodetection fails when a
 624             SCSI controller has multiple disks attached and the SCSI controller
 625             models referenced in the <code>.vmdk</code> files are inconsistent.
 626             <span class="since">Since 0.8.3</span>
 627         </dd><dt><code>buslogic</code></dt><dd>
 628             BusLogic SCSI controller for older guests.
 629         </dd><dt><code>lsilogic</code></dt><dd>
 630             LSI Logic SCSI controller for recent guests.
 631         </dd><dt><code>lsisas1068</code></dt><dd>
 632             LSI Logic SAS 1068 controller. <span class="since">Since 0.8.0</span>
 633         </dd><dt><code>vmpvscsi</code></dt><dd>
 634             Special VMware Paravirtual SCSI controller, requires VMware tools inside
 635             the guest. See <a href="http://kb.vmware.com/kb/1010398" shape="rect">VMware KB1010398</a>
 636             for details. <span class="since">Since 0.8.3</span>
 637         </dd></dl>
 638         <p>
 639         Here a domain XML snippet:
 640     </p>
 641         <pre xml:space="preserve">
 642     ...
 643     &lt;disk type='file' device='disk'&gt;
 644       &lt;source file='[local-storage] Fedora11/Fedora11.vmdk'/&gt;
 645       &lt;target dev='sda' bus='scsi'/&gt;
 646       &lt;address type='drive' controller='0' bus='0' unit='0'/&gt;
 647     &lt;/disk&gt;
 648     &lt;controller type='scsi' index='0' model='<strong>lsilogic</strong>'/&gt;
 649     ...
 650 </pre>
 651         <p>
 652         The controller element is supported <span class="since">since 0.8.2</span>.
 653         Prior to this <code>&lt;driver name='lsilogic'/&gt;</code> was abused to
 654         specify the SCSI controller model. This attribute usage is deprecated now.
 655     </p>
 656         <pre xml:space="preserve">
 657     ...
 658     &lt;disk type='file' device='disk'&gt;
 659       &lt;driver name='<strong>lsilogic</strong>'/&gt;
 660       &lt;source file='[local-storage] Fedora11/Fedora11.vmdk'/&gt;
 661       &lt;target dev='sda' bus='scsi'/&gt;
 662     &lt;/disk&gt;
 663     ...
 664 </pre>
 665         <h4>Network card models</h4>
 666         <dl><dt><code>vlance</code></dt><dd>
 667             AMD PCnet32 network card for older guests.
 668         </dd><dt><code>vmxnet</code>, <code>vmxnet2</code>, <code>vmxnet3</code></dt><dd>
 669             Special VMware VMXnet network card, requires VMware tools inside
 670             the guest. See <a href="http://kb.vmware.com/kb/1001805" shape="rect">VMware KB1001805</a>
 671             for details.
 672         </dd><dt><code>e1000</code></dt><dd>
 673             Intel E1000 network card for recent guests.
 674         </dd></dl>
 675         <p>
 676         Here a domain XML snippet:
 677     </p>
 678         <pre xml:space="preserve">
 679     ...
 680     &lt;interface type='bridge'&gt;
 681       &lt;mac address='00:50:56:25:48:c7'/&gt;
 682       &lt;source bridge='VM Network'/&gt;
 683       &lt;model type='<strong>e1000</strong>'/&gt;
 684     &lt;/interface&gt;
 685     ...
 686 </pre>
 687         <h2>
 688           <a name="importexport" shape="rect" id="importexport">Import and export of domain XML configs</a>
 689           <a class="headerlink" href="#importexport" title="Permalink to this headline">¶</a>
 690         </h2>
 691         <p>
 692         The ESX driver currently supports a native config format known as
 693         <code>vmware-vmx</code> to handle VMware VMX configs.
 694     </p>
 695         <h3>
 696           <a name="xmlimport" shape="rect" id="xmlimport">Converting from VMware VMX config to domain XML config</a>
 697           <a class="headerlink" href="#xmlimport" title="Permalink to this headline">¶</a>
 698         </h3>
 699         <p>
 700         The <code>virsh domxml-from-native</code> provides a way to convert an
 701         existing VMware VMX config into a domain XML config that can then be
 702         used by libvirt.
 703     </p>
 704         <pre xml:space="preserve">
 705 $ cat &gt; demo.vmx &lt;&lt; EOF
 706 #!/usr/bin/vmware
 707 config.version = "8"
 708 virtualHW.version = "4"
 709 floppy0.present = "false"
 710 nvram = "Fedora11.nvram"
 711 deploymentPlatform = "windows"
 712 virtualHW.productCompatibility = "hosted"
 713 tools.upgrade.policy = "useGlobal"
 714 powerType.powerOff = "default"
 715 powerType.powerOn = "default"
 716 powerType.suspend = "default"
 717 powerType.reset = "default"
 718 displayName = "Fedora11"
 719 extendedConfigFile = "Fedora11.vmxf"
 720 scsi0.present = "true"
 721 scsi0.sharedBus = "none"
 722 scsi0.virtualDev = "lsilogic"
 723 memsize = "1024"
 724 scsi0:0.present = "true"
 725 scsi0:0.fileName = "/vmfs/volumes/498076b2-02796c1a-ef5b-000ae484a6a3/Fedora11/Fedora11.vmdk"
 726 scsi0:0.deviceType = "scsi-hardDisk"
 727 ide0:0.present = "true"
 728 ide0:0.clientDevice = "true"
 729 ide0:0.deviceType = "cdrom-raw"
 730 ide0:0.startConnected = "false"
 731 ethernet0.present = "true"
 732 ethernet0.networkName = "VM Network"
 733 ethernet0.addressType = "vpx"
 734 ethernet0.generatedAddress = "00:50:56:91:48:c7"
 735 chipset.onlineStandby = "false"
 736 guestOSAltName = "Red Hat Enterprise Linux 5 (32-Bit)"
 737 guestOS = "rhel5"
 738 uuid.bios = "50 11 5e 16 9b dc 49 d7-f1 71 53 c4 d7 f9 17 10"
 739 snapshot.action = "keep"
 740 sched.cpu.min = "0"
 741 sched.cpu.units = "mhz"
 742 sched.cpu.shares = "normal"
 743 sched.mem.minsize = "0"
 744 sched.mem.shares = "normal"
 745 toolScripts.afterPowerOn = "true"
 746 toolScripts.afterResume = "true"
 747 toolScripts.beforeSuspend = "true"
 748 toolScripts.beforePowerOff = "true"
 749 scsi0:0.redo = ""
 750 tools.syncTime = "false"
 751 uuid.location = "56 4d b5 06 a2 bd fb eb-ae 86 f7 d8 49 27 d0 c4"
 752 sched.cpu.max = "unlimited"
 753 sched.swap.derivedName = "/vmfs/volumes/498076b2-02796c1a-ef5b-000ae484a6a3/Fedora11/Fedora11-7de040d8.vswp"
 754 tools.remindInstall = "TRUE"
 755 EOF
 756
 757 $ virsh -c esx://example.com domxml-from-native vmware-vmx demo.vmx
 758 Enter username for example.com [root]:
 759 Enter root password for example.com:
 760 &lt;domain type='vmware'&gt;
 761   &lt;name&gt;Fedora11&lt;/name&gt;
 762   &lt;uuid&gt;50115e16-9bdc-49d7-f171-53c4d7f91710&lt;/uuid&gt;
 763   &lt;memory&gt;1048576&lt;/memory&gt;
 764   &lt;currentMemory&gt;1048576&lt;/currentMemory&gt;
 765   &lt;vcpu&gt;1&lt;/vcpu&gt;
 766   &lt;os&gt;
 767     &lt;type arch='i686'&gt;hvm&lt;/type&gt;
 768   &lt;/os&gt;
 769   &lt;clock offset='utc'/&gt;
 770   &lt;on_poweroff&gt;destroy&lt;/on_poweroff&gt;
 771   &lt;on_reboot&gt;restart&lt;/on_reboot&gt;
 772   &lt;on_crash&gt;destroy&lt;/on_crash&gt;
 773   &lt;devices&gt;
 774     &lt;disk type='file' device='disk'&gt;
 775       &lt;source file='[local-storage] Fedora11/Fedora11.vmdk'/&gt;
 776       &lt;target dev='sda' bus='scsi'/&gt;
 777       &lt;address type='drive' controller='0' bus='0' unit='0'/&gt;
 778     &lt;/disk&gt;
 779     &lt;controller type='scsi' index='0' model='lsilogic'/&gt;
 780     &lt;interface type='bridge'&gt;
 781       &lt;mac address='00:50:56:91:48:c7'/&gt;
 782       &lt;source bridge='VM Network'/&gt;
 783     &lt;/interface&gt;
 784   &lt;/devices&gt;
 785 &lt;/domain&gt;
 786 </pre>
 787         <h3>
 788           <a name="xmlexport" shape="rect" id="xmlexport">Converting from domain XML config to VMware VMX config</a>
 789           <a class="headerlink" href="#xmlexport" title="Permalink to this headline">¶</a>
 790         </h3>
 791         <p>
 792       The <code>virsh domxml-to-native</code> provides a way to convert a
 793       domain XML config into a VMware VMX config.
 794     </p>
 795         <pre xml:space="preserve">
 796 $ cat &gt; demo.xml &lt;&lt; EOF
 797 &lt;domain type='vmware'&gt;
 798   &lt;name&gt;Fedora11&lt;/name&gt;
 799   &lt;uuid&gt;50115e16-9bdc-49d7-f171-53c4d7f91710&lt;/uuid&gt;
 800   &lt;memory&gt;1048576&lt;/memory&gt;
 801   &lt;currentMemory&gt;1048576&lt;/currentMemory&gt;
 802   &lt;vcpu&gt;1&lt;/vcpu&gt;
 803   &lt;os&gt;
 804     &lt;type arch='x86_64'&gt;hvm&lt;/type&gt;
 805   &lt;/os&gt;
 806   &lt;devices&gt;
 807     &lt;disk type='file' device='disk'&gt;
 808       &lt;source file='[local-storage] Fedora11/Fedora11.vmdk'/&gt;
 809       &lt;target dev='sda' bus='scsi'/&gt;
 810       &lt;address type='drive' controller='0' bus='0' unit='0'/&gt;
 811     &lt;/disk&gt;
 812     &lt;controller type='scsi' index='0' model='lsilogic'/&gt;
 813     &lt;interface type='bridge'&gt;
 814       &lt;mac address='00:50:56:25:48:c7'/&gt;
 815       &lt;source bridge='VM Network'/&gt;
 816     &lt;/interface&gt;
 817   &lt;/devices&gt;
 818 &lt;/domain&gt;
 819 EOF
 820
 821 $ virsh -c esx://example.com domxml-to-native vmware-vmx demo.xml
 822 Enter username for example.com [root]:
 823 Enter root password for example.com:
 824 config.version = "8"
 825 virtualHW.version = "4"
 826 guestOS = "other-64"
 827 uuid.bios = "50 11 5e 16 9b dc 49 d7-f1 71 53 c4 d7 f9 17 10"
 828 displayName = "Fedora11"
 829 memsize = "1024"
 830 numvcpus = "1"
 831 scsi0.present = "true"
 832 scsi0.virtualDev = "lsilogic"
 833 scsi0:0.present = "true"
 834 scsi0:0.deviceType = "scsi-hardDisk"
 835 scsi0:0.fileName = "/vmfs/volumes/local-storage/Fedora11/Fedora11.vmdk"
 836 ethernet0.present = "true"
 837 ethernet0.networkName = "VM Network"
 838 ethernet0.connectionType = "bridged"
 839 ethernet0.addressType = "static"
 840 ethernet0.address = "00:50:56:25:48:C7"
 841 </pre>
 842         <h2>
 843           <a name="xmlconfig" shape="rect" id="xmlconfig">Example domain XML configs</a>
 844           <a class="headerlink" href="#xmlconfig" title="Permalink to this headline">¶</a>
 845         </h2>
 846         <h3>Fedora11 on x86_64</h3>
 847         <pre xml:space="preserve">
 848 &lt;domain type='vmware'&gt;
 849   &lt;name&gt;Fedora11&lt;/name&gt;
 850   &lt;uuid&gt;50115e16-9bdc-49d7-f171-53c4d7f91710&lt;/uuid&gt;
 851   &lt;memory&gt;1048576&lt;/memory&gt;
 852   &lt;currentMemory&gt;1048576&lt;/currentMemory&gt;
 853   &lt;vcpu&gt;1&lt;/vcpu&gt;
 854   &lt;os&gt;
 855     &lt;type arch='x86_64'&gt;hvm&lt;/type&gt;
 856   &lt;/os&gt;
 857   &lt;devices&gt;
 858     &lt;disk type='file' device='disk'&gt;
 859       &lt;source file='[local-storage] Fedora11/Fedora11.vmdk'/&gt;
 860       &lt;target dev='sda' bus='scsi'/&gt;
 861       &lt;address type='drive' controller='0' bus='0' unit='0'/&gt;
 862     &lt;/disk&gt;
 863     &lt;controller type='scsi' index='0'/&gt;
 864     &lt;interface type='bridge'&gt;
 865       &lt;mac address='00:50:56:25:48:c7'/&gt;
 866       &lt;source bridge='VM Network'/&gt;
 867     &lt;/interface&gt;
 868   &lt;/devices&gt;
 869 &lt;/domain&gt;
 870 </pre>
 871         <h2>
 872           <a name="migration" shape="rect" id="migration">Migration</a>
 873           <a class="headerlink" href="#migration" title="Permalink to this headline">¶</a>
 874         </h2>
 875         <p>
 876         A migration cannot be initiated on an ESX server directly, a VMware
 877         vCenter is necessary for this. The <code>vcenter</code> query
 878         parameter must be set either to the hostname or IP address of the
 879         vCenter managing the ESX server or to <code>*</code>. Setting it
 880         to <code>*</code> causes the driver to connect to the vCenter known to
 881         the ESX server. If the ESX server is not managed by a vCenter an error
 882         is reported.
 883     </p>
 884         <pre xml:space="preserve">
 885 esx://example.com/?vcenter=example-vcenter.com
 886 </pre>
 887         <p>
 888         Here's an example how to migrate the domain <code>Fedora11</code> from
 889         ESX server <code>example-src.com</code> to ESX server
 890         <code>example-dst.com</code> implicitly involving vCenter
 891         <code>example-vcenter.com</code> using <code>virsh</code>.
 892     </p>
 893         <pre xml:space="preserve">
 894 $ virsh -c esx://example-src.com/?vcenter=* migrate Fedora11 esx://example-dst.com/?vcenter=*
 895 Enter username for example-src.com [root]:
 896 Enter root password for example-src.com:
 897 Enter username for example-vcenter.com [administrator]:
 898 Enter administrator password for example-vcenter.com:
 899 Enter username for example-dst.com [root]:
 900 Enter root password for example-dst.com:
 901 Enter username for example-vcenter.com [administrator]:
 902 Enter administrator password for example-vcenter.com:
 903 </pre>
 904         <p>
 905         <span class="since">Since 0.8.3</span> you can directly connect to a vCenter.
 906         This simplifies migration a bit. Here's the same migration as above but
 907         using <code>vpx://</code> connections and assuming both ESX server are in
 908         datacenter <code>dc1</code> and aren't part of a cluster.
 909     </p>
 910         <pre xml:space="preserve">
 911 $ virsh -c vpx://example-vcenter.com/dc1/example-src.com migrate Fedora11 vpx://example-vcenter.com/dc1/example-dst.com
 912 Enter username for example-vcenter.com [administrator]:
 913 Enter administrator password for example-vcenter.com:
 914 Enter username for example-vcenter.com [administrator]:
 915 Enter administrator password for example-vcenter.com:
 916 </pre>
 917         <h2>
 918           <a name="scheduler" shape="rect" id="scheduler">Scheduler configuration</a>
 919           <a class="headerlink" href="#scheduler" title="Permalink to this headline">¶</a>
 920         </h2>
 921         <p>
 922         The driver exposes the ESX CPU scheduler. The parameters listed below
 923         are available to control the scheduler.
 924     </p>
 925         <dl><dt><code>reservation</code></dt><dd>
 926             The amount of CPU resource in MHz that is guaranteed to be
 927             available to the domain. Valid values are 0 and greater.
 928         </dd><dt><code>limit</code></dt><dd>
 929             The CPU utilization of the domain will be
 930             limited to this value in MHz, even if more CPU resources are
 931             available. If the limit is set to -1, the CPU utilization of the
 932             domain is unlimited. If the limit is not set to -1, it must be
 933             greater than or equal to the reservation.
 934         </dd><dt><code>shares</code></dt><dd>
 935             Shares are used to determine relative CPU
 936             allocation between domains. In general, a domain with more shares
 937             gets proportionally more of the CPU resource. Valid values are 0
 938             and greater. The special values -1, -2 and -3 represent the
 939             predefined shares level <code>low</code>, <code>normal</code> and
 940             <code>high</code>.
 941         </dd></dl>
 942         <h2>
 943           <a name="tools" shape="rect" id="tools">VMware tools</a>
 944           <a class="headerlink" href="#tools" title="Permalink to this headline">¶</a>
 945         </h2>
 946         <p>
 947         Some actions require installed VMware tools. If the VMware tools are
 948         not installed in the guest and one of the actions below is to be
 949         performed the ESX server raises an error and the driver reports it.
 950     </p>
 951         <ul><li>
 952             <code>virDomainReboot</code>
 953         </li><li>
 954             <code>virDomainShutdown</code>
 955         </li></ul>
 956         <h2>
 957           <a name="links" shape="rect" id="links">Links</a>
 958           <a class="headerlink" href="#links" title="Permalink to this headline">¶</a>
 959         </h2>
 960         <ul><li>
 961             <a href="http://www.vmware.com/support/developer/vc-sdk/" shape="rect">
 962                 VMware vSphere Web Services SDK Documentation
 963             </a>
 964         </li><li>
 965             <a href="http://www.vmware.com/pdf/esx3_memory.pdf" shape="rect">
 966                 The Role of Memory in VMware ESX Server 3
 967             </a>
 968         </li><li>
 969             <a href="http://www.sanbarrow.com/vmx.html" shape="rect">
 970                 VMware VMX config parameters
 971             </a>
 972         </li><li>
 973             <a href="http://www.vmware.com/pdf/vsp_4_pvscsi_perf.pdf" shape="rect">
 974                 VMware ESX 4.0 PVSCSI Storage Performance
 975             </a>
 976         </li></ul>
 977       </div>
 978     </div>
 979     <div id="footer">
 980       <p id="sponsor">
 981             Sponsored by:<br /><a href="http://et.redhat.com/"><img src="et.png" alt="Project sponsored by Red Hat Emerging Technology" /></a></p>
 982     </div>
 983   </body>
 984 </html>