docs/drvesx.rst

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