docs/drvesx.html.in

   1 <html><body>
   2     <h1>VMware ESX hypervisor driver</h1>
   3     <ul id="toc"></ul>
   4     <p>
   5         The libvirt VMware ESX driver can manage VMware ESX/ESXi 3.5/4.x and
   6         VMware GSX 2.0, also called VMware Server 2.0, and possibly later
   7         versions. <span class="since">Since 0.8.3</span> the driver can also
   8         connect to a VMware vCenter 2.5/4.x (VPX).
   9     </p>
  10
  11     <h2><a name="project">Project Links</a></h2>
  12
  13     <ul>
  14       <li>
  15         The <a href="http://www.vmware.com/">VMware ESX and GSX</a>
  16         hypervisors
  17       </li>
  18     </ul>
  19
  20     <h2><a name="prereq">Deployment pre-requisites</a></h2>
  21     <p>
  22         None. Any out-of-the-box installation of VPX/ESX(i)/GSX should work. No
  23         preparations are required on the server side, no libvirtd must be
  24         installed on the ESX server. The driver uses version 2.5 of the remote,
  25         SOAP based
  26         <a href="http://www.vmware.com/support/developer/vc-sdk/visdk25pubs/ReferenceGuide/">
  27         VMware Virtual Infrastructure API</a> (VI API) to communicate with the
  28         ESX server, like the VMware Virtual Infrastructure Client (VI client)
  29         does. Since version 4.0 this API is called
  30         <a href="http://www.vmware.com/support/developer/vc-sdk/visdk400pubs/ReferenceGuide/">
  31         VMware vSphere API</a>.
  32     </p>
  33
  34     <h2><a name="uri">Connections to the VMware ESX driver</a></h2>
  35     <p>
  36         Some example remote connection URIs for the driver are:
  37     </p>
  38 <pre>
  39 vpx://example-vcenter.com/dc1/srv1     (VPX over HTTPS, select ESX server 'srv1' in datacenter 'dc1')
  40 esx://example-esx.com                  (ESX over HTTPS)
  41 gsx://example-gsx.com                  (GSX over HTTPS)
  42 esx://example-esx.com/?transport=http  (ESX over HTTP)
  43 esx://example-esx.com/?no_verify=1     (ESX over HTTPS, but doesn't verify the server's SSL certificate)
  44 </pre>
  45     <p>
  46         <strong>Note</strong>: In contrast to other drivers, the ESX driver is
  47         a client-side-only driver. It connects to the ESX server using HTTP(S).
  48         Therefore, the <a href="remote.html">remote transport mechanism</a>
  49         provided by the remote driver and libvirtd will not work, and you
  50         cannot use URIs like <code>esx+ssh://example.com</code>.
  51     </p>
  52
  53
  54     <h3><a name="uriformat">URI Format</a></h3>
  55     <p>
  56         URIs have this general form (<code>[...]</code> marks an optional part).
  57     </p>
  58 <pre>
  59 type://[username@]hostname[:port]/[datacenter[/cluster]/server][?extraparameters]
  60 </pre>
  61     <p>
  62         The <code>type://</code> is either <code>esx://</code> or
  63         <code>gsx://</code> or <code>vpx://</code> <span class="since">since 0.8.3</span>.
  64         The driver selects the default port depending on the <code>type://</code>.
  65         For <code>esx://</code> and <code>vpx://</code> the default HTTPS port
  66         is 443, for <code>gsx://</code> it is 8333.
  67         If the port parameter is given, it overrides the default port.
  68     </p>
  69     <p>
  70         A <code>vpx://</code> connection is currently restricted to a single
  71         ESX server. This might be relaxed in the future. The path part of the
  72         URI is used to specify the datacenter and the ESX server in it. If the
  73         ESX server is part of a cluster then the cluster has to be specified too.
  74     </p>
  75     <p>
  76         An example: ESX server <code>example-esx.com</code> is managed by
  77         vCenter <code>example-vcenter.com</code> and part of cluster
  78         <code>cluster1</code>. This cluster is part of datacenter <code>dc1</code>.
  79     </p>
  80 <pre>
  81 vpx://example-vcenter.com/dc1/cluster1/example-esx.com
  82 </pre>
  83
  84
  85     <h4><a name="extraparams">Extra parameters</a></h4>
  86     <p>
  87         Extra parameters can be added to a URI as part of the query string
  88         (the part following <code>?</code>). A single parameter is formed by a
  89         <code>name=value</code> pair. Multiple parameters are separated by
  90         <code>&amp;</code>.
  91     </p>
  92 <pre>
  93 ?<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>
  94 </pre>
  95     <p>
  96         The driver understands the extra parameters shown below.
  97     </p>
  98     <table class="top_table">
  99         <tr>
 100             <th>Name</th>
 101             <th>Values</th>
 102             <th>Meaning</th>
 103         </tr>
 104         <tr>
 105             <td>
 106                 <code>transport</code>
 107             </td>
 108             <td>
 109                 <code>http</code> or <code>https</code>
 110             </td>
 111             <td>
 112                 Overrides the default HTTPS transport. For <code>esx://</code>
 113                 and <code>vpx://</code> the default HTTP port is 80, for
 114                 <code>gsx://</code> it is 8222.
 115             </td>
 116         </tr>
 117         <tr>
 118             <td>
 119                 <code>vcenter</code>
 120             </td>
 121             <td>
 122                 Hostname of a VMware vCenter or <code>*</code>
 123             </td>
 124             <td>
 125                 In order to perform a migration the driver needs to know the
 126                 VMware vCenter for the ESX server. If set to <code>*</code>,
 127                 the driver connects to the vCenter known to the ESX server.
 128                 This parameter in useful when connecting to an ESX server only.
 129             </td>
 130         </tr>
 131         <tr>
 132             <td>
 133                 <code>no_verify</code>
 134             </td>
 135             <td>
 136                 <code>0</code> or <code>1</code>
 137             </td>
 138             <td>
 139                 If set to 1, this disables libcurl client checks of the server's
 140                 SSL certificate. The default value it 0. See the
 141                 <a href="#certificates">Certificates for HTTPS</a> section for
 142                 details.
 143             </td>
 144         </tr>
 145         <tr>
 146             <td>
 147                 <code>auto_answer</code>
 148             </td>
 149             <td>
 150                 <code>0</code> or <code>1</code>
 151             </td>
 152             <td>
 153                 If set to 1, the driver answers all
 154                 <a href="#questions">questions</a> with the default answer.
 155                 If set to 0, questions are reported as errors. The default
 156                 value it 0. <span class="since">Since 0.7.5</span>.
 157             </td>
 158         </tr>
 159         <tr>
 160             <td>
 161                 <code>proxy</code>
 162             </td>
 163             <td>
 164                 <code>[type://]hostname[:port]</code>
 165             </td>
 166             <td>
 167                 Allows to specify a proxy for HTTP and HTTPS communication.
 168                 <span class="since">Since 0.8.2</span>.
 169                 The optional <code>type</code> part may be one of:
 170                 <code>http</code>, <code>socks</code>, <code>socks4</code>,
 171                 <code>socks4a</code> or <code>socks5</code>. The default is
 172                 <code>http</code> and <code>socks</code> is synonymous for
 173                 <code>socks5</code>. The optional <code>port</code> allows to
 174                 override the default port 1080.
 175             </td>
 176         </tr>
 177     </table>
 178
 179
 180     <h3><a name="auth">Authentication</a></h3>
 181     <p>
 182         In order to perform any useful operation the driver needs to log into
 183         the ESX server. Therefore, only <code>virConnectOpenAuth</code> can be
 184         used to connect to an ESX server, <code>virConnectOpen</code> and
 185         <code>virConnectOpenReadOnly</code> don't work.
 186         To log into an ESX server or vCenter the driver will request
 187         credentials using the callback passed to the
 188         <code>virConnectOpenAuth</code> function. The driver passes the
 189         hostname as challenge parameter to the callback. This enables the
 190         callback to distinguish between requests for ESX server and vCenter.
 191     </p>
 192     <p>
 193         <strong>Note</strong>: During the ongoing driver development, testing
 194         is done using an unrestricted <code>root</code> account. Problems may
 195         occur if you use a restricted account. Detailed testing with restricted
 196         accounts has not been done yet.
 197     </p>
 198
 199
 200     <h3><a name="certificates">Certificates for HTTPS</a></h3>
 201     <p>
 202         By default the ESX driver uses HTTPS to communicate with an ESX server.
 203         Proper HTTPS communication requires correctly configured SSL
 204         certificates. This certificates are different from the ones libvirt
 205         uses for <a href="remote.html">secure communication over TLS</a> to a
 206         libvirtd one a remote server.
 207     </p>
 208     <p>
 209         By default the driver tries to verify the server's SSL certificate
 210         using the CA certificate pool installed on your client computer. With
 211         an out-of-the-box installed ESX server this won't work, because a newly
 212         installed ESX server uses auto-generated self-signed certificates.
 213         Those are singed by a CA certificate that is typically not known to your
 214         client computer and libvirt will report an error like this one:
 215     </p>
 216 <pre>
 217 error: internal error curl_easy_perform() returned an error: Peer certificate cannot be authenticated with known CA certificates (60)
 218 </pre>
 219     <p>
 220         Where are two ways to solve this problem:
 221     </p>
 222     <ul>
 223         <li>
 224             Use the <code>no_verify=1</code> <a href="#extraparams">extra parameter</a>
 225             to disable server certificate verification.
 226         </li>
 227         <li>
 228             Generate new SSL certificates signed by a CA known to your client
 229             computer and replace the original ones on your ESX server. See the
 230             section <i>Replace a Default Certificate with a CA-Signed Certificate</i>
 231             in the <a href="http://www.vmware.com/pdf/vsphere4/r40/vsp_40_esx_server_config.pdf">ESX Configuration Guide</a>
 232         </li>
 233     </ul>
 234
 235
 236     <h3><a name="connproblems">Connection problems</a></h3>
 237     <p>
 238         There are also other causes for connection problems than the
 239         <a href="#certificates">HTTPS certificate</a> related ones.
 240     </p>
 241     <ul>
 242         <li>
 243             As stated before the ESX driver doesn't need the
 244             <a href="remote.html">remote transport mechanism</a>
 245             provided by the remote driver and libvirtd, nor does the ESX driver
 246             support it. Therefore, using an URI including a transport in the
 247             scheme won't work. Only <a href="#uriformat">URIs as described</a>
 248             are supported by the ESX driver. Here's a collection of possible
 249             error messages:
 250 <pre>
 251 $ virsh -c esx+tcp://example.com/
 252 error: unable to connect to libvirtd at 'example.com': Connection refused
 253 </pre>
 254 <pre>
 255 $ virsh -c esx+tls://example.com/
 256 error: Cannot access CA certificate '/etc/pki/CA/cacert.pem': No such file or directory
 257 </pre>
 258 <pre>
 259 $ virsh -c esx+ssh://example.com/
 260 error: cannot recv data: ssh: connect to host example.com port 22: Connection refused
 261 </pre>
 262 <pre>
 263 $ virsh -c esx+ssh://example.com/
 264 error: cannot recv data: Resource temporarily unavailable
 265 </pre>
 266         </li>
 267         <li>
 268             <span class="since">Since 0.7.0</span> libvirt contains the ESX
 269             driver. Earlier versions of libvirt will report a misleading error
 270             about missing certificates when you try to connect to an ESX server.
 271 <pre>
 272 $ virsh -c esx://example.com/
 273 error: Cannot access CA certificate '/etc/pki/CA/cacert.pem': No such file or directory
 274 </pre>
 275             <p>
 276                 Don't let this error message confuse you. Setting up certificates
 277                 as described on the <a href="remote.html#Remote_certificates">remote transport mechanism</a> page
 278                 does not help, as this is not a certificate related problem.
 279             </p>
 280             <p>
 281                 To fix this problem you need to update your libvirt to 0.7.0 or newer.
 282                 You may also see this error when you use a libvirt version that
 283                 contains the ESX driver but you or your distro disabled the ESX
 284                 driver during compilation. <span class="since">Since 0.8.3</span>
 285                 the error message has been improved in this case:
 286             </p>
 287 <pre>
 288 $ virsh -c esx://example.com/
 289 error: invalid argument in libvirt was built without the 'esx' driver
 290 </pre>
 291         </li>
 292     </ul>
 293
 294
 295     <h2><a name="questions">Questions blocking tasks</a></h2>
 296     <p>
 297         Some methods of the VI API start tasks, for example
 298         <code>PowerOnVM_Task()</code>. Such tasks may be blocked by questions
 299         if the ESX server detects an issue with the domain that requires user
 300         interaction. The ESX driver cannot prompt the user to answer a
 301         question, libvirt doesn't have an API for something like this.
 302     </p>
 303     <p>
 304         The VI API provides the <code>AnswerVM()</code> method to
 305         programmatically answer a questions. So the driver has two options
 306         how to handle such a situation: either answer the questions with the
 307         default answer or report the question as an error and cancel the
 308         blocked task if possible. The
 309         <a href="#uriformat"><code>auto_answer</code></a> query parameter
 310         controls the answering behavior.
 311     </p>
 312
 313
 314     <h2><a name="xmlspecial">Specialties in the domain XML config</a></h2>
 315     <p>
 316         There are several specialties in the domain XML config for ESX domains.
 317     </p>
 318
 319     <h3><a name="restrictions">Restrictions</a></h3>
 320     <p>
 321         There are some restrictions for some values of the domain XML config.
 322         The driver will complain if this restrictions are violated.
 323     </p>
 324     <ul>
 325         <li>
 326             Memory size has to be a multiple of 4096
 327         </li>
 328         <li>
 329             Number of virtual CPU has to be 1 or a multiple of 2
 330         </li>
 331         <li>
 332             Valid MAC address prefixes are <code>00:0c:29</code> and
 333             <code>00:50:56</code>. <span class="since">Since 0.7.6</span>
 334             arbitrary <a href="#macaddresses">MAC addresses</a> are supported.
 335         </li>
 336     </ul>
 337
 338
 339     <h3><a name="datastore">Datastore references</a></h3>
 340     <p>
 341         Storage is managed in datastores. VMware uses a special path format to
 342         reference files in a datastore. Basically, the datastore name is put
 343         into squared braces in front of the path.
 344     </p>
 345 <pre>
 346 [datastore] directory/filename
 347 </pre>
 348     <p>
 349         To define a new domain the driver converts the domain XML into a
 350         VMware VMX file and uploads it to a datastore known to the ESX server.
 351         Because multiple datastores may be known to an ESX server the driver
 352         needs to decide to which datastore the VMX file should be uploaded.
 353         The driver deduces this information from the path of the source of the
 354         first file-based harddisk listed in the domain XML.
 355     </p>
 356
 357
 358     <h3><a name="macaddresses">MAC addresses</a></h3>
 359     <p>
 360         VMware has registered two MAC address prefixes for domains:
 361         <code>00:0c:29</code> and <code>00:50:56</code>. These prefixes are
 362         split into ranges for different purposes.
 363     </p>
 364     <table class="top_table">
 365         <tr>
 366             <th>Range</th>
 367             <th>Purpose</th>
 368         </tr>
 369         <tr>
 370             <td>
 371                 <code>00:0c:29:00:00:00</code> - <code>00:0c:29:ff:ff:ff</code>
 372             </td>
 373             <td>
 374                 An ESX server autogenerates MAC addresses from this range if
 375                 the VMX file doesn't contain a MAC address when trying to start
 376                 a domain.
 377             </td>
 378         </tr>
 379         <tr>
 380             <td>
 381                 <code>00:50:56:00:00:00</code> - <code>00:50:56:3f:ff:ff</code>
 382             </td>
 383             <td>
 384                 MAC addresses from this range can by manually assigned by the
 385                 user in the VI client.
 386             </td>
 387         </tr>
 388         <tr>
 389             <td>
 390                 <code>00:50:56:80:00:00</code> - <code>00:50:56:bf:ff:ff</code>
 391             </td>
 392             <td>
 393                 A VI client autogenerates MAC addresses from this range for
 394                 newly defined domains.
 395             </td>
 396         </tr>
 397     </table>
 398     <p>
 399         The VMX files generated by the ESX driver always contain a MAC address,
 400         because libvirt generates a random one if an interface element in the
 401         domain XML file lacks a MAC address.
 402         <span class="since">Since 0.7.6</span> the ESX driver sets the prefix
 403         for generated MAC addresses to <code>00:0c:29</code>. Before 0.7.6
 404         the <code>00:50:56</code> prefix was used. Sometimes this resulted in
 405         the generation of out-of-range MAC address that were rejected by the
 406         ESX server.
 407     </p>
 408     <p>
 409         Also <span class="since">since 0.7.6</span> every MAC address outside
 410         this ranges can be used. For such MAC addresses the ESX server-side
 411         check is disabled in the VMX file to stop the ESX server from rejecting
 412         out-of-predefined-range MAC addresses.
 413     </p>
 414 <pre>
 415 ethernet0.checkMACAddress = "false"
 416 </pre>
 417
 418
 419     <h3><a name="hardware">Available hardware</a></h3>
 420     <p>
 421         VMware ESX supports different models of SCSI controllers and network
 422         cards.
 423     </p>
 424
 425     <h4>SCSI controller models</h4>
 426     <dl>
 427         <dt><code>auto</code></dt>
 428         <dd>
 429             This isn't a actual controller model. If specified the ESX driver
 430             tries to detect the SCSI controller model referenced in the
 431             <code>.vmdk</code> file and use it. Autodetection fails when a
 432             SCSI controller has multiple disks attached and the SCSI controller
 433             models referenced in the <code>.vmdk</code> files are inconsistent.
 434             <span class="since">Since 0.8.3</span>
 435         </dd>
 436         <dt><code>buslogic</code></dt>
 437         <dd>
 438             BusLogic SCSI controller for older guests.
 439         </dd>
 440         <dt><code>lsilogic</code></dt>
 441         <dd>
 442             LSI Logic SCSI controller for recent guests.
 443         </dd>
 444         <dt><code>lsisas1068</code></dt>
 445         <dd>
 446             LSI Logic SAS 1068 controller. <span class="since">Since 0.8.0</span>
 447         </dd>
 448         <dt><code>vmpvscsi</code></dt>
 449         <dd>
 450             Special VMware Paravirtual SCSI controller, requires VMware tools inside
 451             the guest. See <a href="http://kb.vmware.com/kb/1010398">VMware KB1010398</a>
 452             for details. <span class="since">Since 0.8.3</span>
 453         </dd>
 454     </dl>
 455     <p>
 456         Here a domain XML snippet:
 457     </p>
 458 <pre>
 459     ...
 460     &lt;disk type='file' device='disk'&gt;
 461       &lt;source file='[local-storage] Fedora11/Fedora11.vmdk'/&gt;
 462       &lt;target dev='sda' bus='scsi'/&gt;
 463       &lt;address type='drive' controller='0' bus='0' unit='0'/&gt;
 464     &lt;/disk&gt;
 465     &lt;controller type='scsi' index='0' model='<strong>lsilogic</strong>'/&gt;
 466     ...
 467 </pre>
 468     <p>
 469         The controller element is supported <span class="since">since 0.8.2</span>.
 470         Prior to this <code>&lt;driver name='lsilogic'/&gt;</code> was abused to
 471         specify the SCSI controller model. This attribute usage is deprecated now.
 472     </p>
 473 <pre>
 474     ...
 475     &lt;disk type='file' device='disk'&gt;
 476       &lt;driver name='<strong>lsilogic</strong>'/&gt;
 477       &lt;source file='[local-storage] Fedora11/Fedora11.vmdk'/&gt;
 478       &lt;target dev='sda' bus='scsi'/&gt;
 479     &lt;/disk&gt;
 480     ...
 481 </pre>
 482
 483
 484     <h4>Network card models</h4>
 485     <dl>
 486         <dt><code>vlance</code></dt>
 487         <dd>
 488             AMD PCnet32 network card for older guests.
 489         </dd>
 490         <dt><code>vmxnet</code>, <code>vmxnet2</code>, <code>vmxnet3</code></dt>
 491         <dd>
 492             Special VMware VMXnet network card, requires VMware tools inside
 493             the guest. See <a href="http://kb.vmware.com/kb/1001805">VMware KB1001805</a>
 494             for details.
 495         </dd>
 496         <dt><code>e1000</code></dt>
 497         <dd>
 498             Intel E1000 network card for recent guests.
 499         </dd>
 500     </dl>
 501     <p>
 502         Here a domain XML snippet:
 503     </p>
 504 <pre>
 505     ...
 506     &lt;interface type='bridge'&gt;
 507       &lt;mac address='00:50:56:25:48:c7'/&gt;
 508       &lt;source bridge='VM Network'/&gt;
 509       &lt;model type='<strong>e1000</strong>'/&gt;
 510     &lt;/interface&gt;
 511     ...
 512 </pre>
 513
 514
 515     <h2><a name="importexport">Import and export of domain XML configs</a></h2>
 516     <p>
 517         The ESX driver currently supports a native config format known as
 518         <code>vmware-vmx</code> to handle VMware VMX configs.
 519     </p>
 520
 521
 522     <h3><a name="xmlimport">Converting from VMware VMX config to domain XML config</a></h3>
 523     <p>
 524         The <code>virsh domxml-from-native</code> provides a way to convert an
 525         existing VMware VMX config into a domain XML config that can then be
 526         used by libvirt.
 527     </p>
 528 <pre>
 529 $ cat &gt; demo.vmx &lt;&lt; EOF
 530 #!/usr/bin/vmware
 531 config.version = "8"
 532 virtualHW.version = "4"
 533 floppy0.present = "false"
 534 nvram = "Fedora11.nvram"
 535 deploymentPlatform = "windows"
 536 virtualHW.productCompatibility = "hosted"
 537 tools.upgrade.policy = "useGlobal"
 538 powerType.powerOff = "default"
 539 powerType.powerOn = "default"
 540 powerType.suspend = "default"
 541 powerType.reset = "default"
 542 displayName = "Fedora11"
 543 extendedConfigFile = "Fedora11.vmxf"
 544 scsi0.present = "true"
 545 scsi0.sharedBus = "none"
 546 scsi0.virtualDev = "lsilogic"
 547 memsize = "1024"
 548 scsi0:0.present = "true"
 549 scsi0:0.fileName = "/vmfs/volumes/498076b2-02796c1a-ef5b-000ae484a6a3/Fedora11/Fedora11.vmdk"
 550 scsi0:0.deviceType = "scsi-hardDisk"
 551 ide0:0.present = "true"
 552 ide0:0.clientDevice = "true"
 553 ide0:0.deviceType = "cdrom-raw"
 554 ide0:0.startConnected = "false"
 555 ethernet0.present = "true"
 556 ethernet0.networkName = "VM Network"
 557 ethernet0.addressType = "vpx"
 558 ethernet0.generatedAddress = "00:50:56:91:48:c7"
 559 chipset.onlineStandby = "false"
 560 guestOSAltName = "Red Hat Enterprise Linux 5 (32-Bit)"
 561 guestOS = "rhel5"
 562 uuid.bios = "50 11 5e 16 9b dc 49 d7-f1 71 53 c4 d7 f9 17 10"
 563 snapshot.action = "keep"
 564 sched.cpu.min = "0"
 565 sched.cpu.units = "mhz"
 566 sched.cpu.shares = "normal"
 567 sched.mem.minsize = "0"
 568 sched.mem.shares = "normal"
 569 toolScripts.afterPowerOn = "true"
 570 toolScripts.afterResume = "true"
 571 toolScripts.beforeSuspend = "true"
 572 toolScripts.beforePowerOff = "true"
 573 scsi0:0.redo = ""
 574 tools.syncTime = "false"
 575 uuid.location = "56 4d b5 06 a2 bd fb eb-ae 86 f7 d8 49 27 d0 c4"
 576 sched.cpu.max = "unlimited"
 577 sched.swap.derivedName = "/vmfs/volumes/498076b2-02796c1a-ef5b-000ae484a6a3/Fedora11/Fedora11-7de040d8.vswp"
 578 tools.remindInstall = "TRUE"
 579 EOF
 580
 581 $ virsh -c esx://example.com domxml-from-native vmware-vmx demo.vmx
 582 Enter username for example.com [root]:
 583 Enter root password for example.com:
 584 &lt;domain type='vmware'&gt;
 585   &lt;name&gt;Fedora11&lt;/name&gt;
 586   &lt;uuid&gt;50115e16-9bdc-49d7-f171-53c4d7f91710&lt;/uuid&gt;
 587   &lt;memory&gt;1048576&lt;/memory&gt;
 588   &lt;currentMemory&gt;1048576&lt;/currentMemory&gt;
 589   &lt;vcpu&gt;1&lt;/vcpu&gt;
 590   &lt;os&gt;
 591     &lt;type arch='i686'&gt;hvm&lt;/type&gt;
 592   &lt;/os&gt;
 593   &lt;clock offset='utc'/&gt;
 594   &lt;on_poweroff&gt;destroy&lt;/on_poweroff&gt;
 595   &lt;on_reboot&gt;restart&lt;/on_reboot&gt;
 596   &lt;on_crash&gt;destroy&lt;/on_crash&gt;
 597   &lt;devices&gt;
 598     &lt;disk type='file' device='disk'&gt;
 599       &lt;source file='[local-storage] Fedora11/Fedora11.vmdk'/&gt;
 600       &lt;target dev='sda' bus='scsi'/&gt;
 601       &lt;address type='drive' controller='0' bus='0' unit='0'/&gt;
 602     &lt;/disk&gt;
 603     &lt;controller type='scsi' index='0' model='lsilogic'/&gt;
 604     &lt;interface type='bridge'&gt;
 605       &lt;mac address='00:50:56:91:48:c7'/&gt;
 606       &lt;source bridge='VM Network'/&gt;
 607     &lt;/interface&gt;
 608   &lt;/devices&gt;
 609 &lt;/domain&gt;
 610 </pre>
 611
 612
 613     <h3><a name="xmlexport">Converting from domain XML config to VMware VMX config</a></h3>
 614     <p>
 615       The <code>virsh domxml-to-native</code> provides a way to convert a
 616       domain XML config into a VMware VMX config.
 617     </p>
 618 <pre>
 619 $ cat &gt; demo.xml &lt;&lt; EOF
 620 &lt;domain type='vmware'&gt;
 621   &lt;name&gt;Fedora11&lt;/name&gt;
 622   &lt;uuid&gt;50115e16-9bdc-49d7-f171-53c4d7f91710&lt;/uuid&gt;
 623   &lt;memory&gt;1048576&lt;/memory&gt;
 624   &lt;currentMemory&gt;1048576&lt;/currentMemory&gt;
 625   &lt;vcpu&gt;1&lt;/vcpu&gt;
 626   &lt;os&gt;
 627     &lt;type arch='x86_64'&gt;hvm&lt;/type&gt;
 628   &lt;/os&gt;
 629   &lt;devices&gt;
 630     &lt;disk type='file' device='disk'&gt;
 631       &lt;source file='[local-storage] Fedora11/Fedora11.vmdk'/&gt;
 632       &lt;target dev='sda' bus='scsi'/&gt;
 633       &lt;address type='drive' controller='0' bus='0' unit='0'/&gt;
 634     &lt;/disk&gt;
 635     &lt;controller type='scsi' index='0' model='lsilogic'/&gt;
 636     &lt;interface type='bridge'&gt;
 637       &lt;mac address='00:50:56:25:48:c7'/&gt;
 638       &lt;source bridge='VM Network'/&gt;
 639     &lt;/interface&gt;
 640   &lt;/devices&gt;
 641 &lt;/domain&gt;
 642 EOF
 643
 644 $ virsh -c esx://example.com domxml-to-native vmware-vmx demo.xml
 645 Enter username for example.com [root]:
 646 Enter root password for example.com:
 647 config.version = "8"
 648 virtualHW.version = "4"
 649 guestOS = "other-64"
 650 uuid.bios = "50 11 5e 16 9b dc 49 d7-f1 71 53 c4 d7 f9 17 10"
 651 displayName = "Fedora11"
 652 memsize = "1024"
 653 numvcpus = "1"
 654 scsi0.present = "true"
 655 scsi0.virtualDev = "lsilogic"
 656 scsi0:0.present = "true"
 657 scsi0:0.deviceType = "scsi-hardDisk"
 658 scsi0:0.fileName = "/vmfs/volumes/local-storage/Fedora11/Fedora11.vmdk"
 659 ethernet0.present = "true"
 660 ethernet0.networkName = "VM Network"
 661 ethernet0.connectionType = "bridged"
 662 ethernet0.addressType = "static"
 663 ethernet0.address = "00:50:56:25:48:C7"
 664 </pre>
 665
 666
 667     <h2><a name="xmlconfig">Example domain XML configs</a></h2>
 668
 669     <h3>Fedora11 on x86_64</h3>
 670 <pre>
 671 &lt;domain type='vmware'&gt;
 672   &lt;name&gt;Fedora11&lt;/name&gt;
 673   &lt;uuid&gt;50115e16-9bdc-49d7-f171-53c4d7f91710&lt;/uuid&gt;
 674   &lt;memory&gt;1048576&lt;/memory&gt;
 675   &lt;currentMemory&gt;1048576&lt;/currentMemory&gt;
 676   &lt;vcpu&gt;1&lt;/vcpu&gt;
 677   &lt;os&gt;
 678     &lt;type arch='x86_64'&gt;hvm&lt;/type&gt;
 679   &lt;/os&gt;
 680   &lt;devices&gt;
 681     &lt;disk type='file' device='disk'&gt;
 682       &lt;source file='[local-storage] Fedora11/Fedora11.vmdk'/&gt;
 683       &lt;target dev='sda' bus='scsi'/&gt;
 684       &lt;address type='drive' controller='0' bus='0' unit='0'/&gt;
 685     &lt;/disk&gt;
 686     &lt;controller type='scsi' index='0'/&gt;
 687     &lt;interface type='bridge'&gt;
 688       &lt;mac address='00:50:56:25:48:c7'/&gt;
 689       &lt;source bridge='VM Network'/&gt;
 690     &lt;/interface&gt;
 691   &lt;/devices&gt;
 692 &lt;/domain&gt;
 693 </pre>
 694
 695
 696     <h2><a name="migration">Migration</a></h2>
 697     <p>
 698         A migration cannot be initiated on an ESX server directly, a VMware
 699         vCenter is necessary for this. The <code>vcenter</code> query
 700         parameter must be set either to the hostname or IP address of the
 701         vCenter managing the ESX server or to <code>*</code>. Setting it
 702         to <code>*</code> causes the driver to connect to the vCenter known to
 703         the ESX server. If the ESX server is not managed by a vCenter an error
 704         is reported.
 705     </p>
 706 <pre>
 707 esx://example.com/?vcenter=example-vcenter.com
 708 </pre>
 709     <p>
 710         Here's an example how to migrate the domain <code>Fedora11</code> from
 711         ESX server <code>example-src.com</code> to ESX server
 712         <code>example-dst.com</code> implicitly involving vCenter
 713         <code>example-vcenter.com</code> using <code>virsh</code>.
 714     </p>
 715 <pre>
 716 $ virsh -c esx://example-src.com/?vcenter=* migrate Fedora11 esx://example-dst.com/?vcenter=*
 717 Enter username for example-src.com [root]:
 718 Enter root password for example-src.com:
 719 Enter username for example-vcenter.com [administrator]:
 720 Enter administrator password for example-vcenter.com:
 721 Enter username for example-dst.com [root]:
 722 Enter root password for example-dst.com:
 723 Enter username for example-vcenter.com [administrator]:
 724 Enter administrator password for example-vcenter.com:
 725 </pre>
 726     <p>
 727         <span class="since">Since 0.8.3</span> you can directly connect to a vCenter.
 728         This simplifies migration a bit. Here's the same migration as above but
 729         using <code>vpx://</code> connections and assuming both ESX server are in
 730         datacenter <code>dc1</code> and aren't part of a cluster.
 731     </p>
 732 <pre>
 733 $ virsh -c vpx://example-vcenter.com/dc1/example-src.com migrate Fedora11 vpx://example-vcenter.com/dc1/example-dst.com
 734 Enter username for example-vcenter.com [administrator]:
 735 Enter administrator password for example-vcenter.com:
 736 Enter username for example-vcenter.com [administrator]:
 737 Enter administrator password for example-vcenter.com:
 738 </pre>
 739
 740
 741     <h2><a name="scheduler">Scheduler configuration</a></h2>
 742     <p>
 743         The driver exposes the ESX CPU scheduler. The parameters listed below
 744         are available to control the scheduler.
 745     </p>
 746     <dl>
 747         <dt><code>reservation</code></dt>
 748         <dd>
 749             The amount of CPU resource in MHz that is guaranteed to be
 750             available to the domain. Valid values are 0 and greater.
 751         </dd>
 752         <dt><code>limit</code></dt>
 753         <dd>
 754             The CPU utilization of the domain will be
 755             limited to this value in MHz, even if more CPU resources are
 756             available. If the limit is set to -1, the CPU utilization of the
 757             domain is unlimited. If the limit is not set to -1, it must be
 758             greater than or equal to the reservation.
 759         </dd>
 760         <dt><code>shares</code></dt>
 761         <dd>
 762             Shares are used to determine relative CPU
 763             allocation between domains. In general, a domain with more shares
 764             gets proportionally more of the CPU resource. Valid values are 0
 765             and greater. The special values -1, -2 and -3 represent the
 766             predefined shares level <code>low</code>, <code>normal</code> and
 767             <code>high</code>.
 768         </dd>
 769     </dl>
 770
 771
 772     <h2><a name="tools">VMware tools</a></h2>
 773     <p>
 774         Some actions require installed VMware tools. If the VMware tools are
 775         not installed in the guest and one of the actions below is to be
 776         performed the ESX server raises an error and the driver reports it.
 777     </p>
 778     <ul>
 779         <li>
 780             <code>virDomainReboot</code>
 781         </li>
 782         <li>
 783             <code>virDomainShutdown</code>
 784         </li>
 785     </ul>
 786
 787
 788     <h2><a name="links">Links</a></h2>
 789     <ul>
 790         <li>
 791             <a href="http://www.vmware.com/support/developer/vc-sdk/">
 792                 VMware vSphere Web Services SDK Documentation
 793             </a>
 794         </li>
 795         <li>
 796             <a href="http://www.vmware.com/pdf/esx3_memory.pdf">
 797                 The Role of Memory in VMware ESX Server 3
 798             </a>
 799         </li>
 800         <li>
 801             <a href="http://www.sanbarrow.com/vmx.html">
 802                 VMware VMX config parameters
 803             </a>
 804         </li>
 805         <li>
 806             <a href="http://www.vmware.com/pdf/vsp_4_pvscsi_perf.pdf">
 807                 VMware ESX 4.0 PVSCSI Storage Performance
 808             </a>
 809         </li>
 810     </ul>
 811 </body></html>