[PATCH 04/29] docs: Convert 'drvesx' page to rST
Peter Krempa
pkrempa at redhat.com
Mon Mar 28 12:10:19 UTC 2022
Signed-off-by: Peter Krempa <pkrempa at redhat.com>
---
docs/drvesx.html.in | 838 --------------------------------------------
docs/drvesx.rst | 681 +++++++++++++++++++++++++++++++++++
docs/meson.build | 2 +-
3 files changed, 682 insertions(+), 839 deletions(-)
delete mode 100644 docs/drvesx.html.in
create mode 100644 docs/drvesx.rst
diff --git a/docs/drvesx.html.in b/docs/drvesx.html.in
deleted file mode 100644
index c56da16f57..0000000000
--- a/docs/drvesx.html.in
+++ /dev/null
@@ -1,838 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
- <body>
- <h1>VMware ESX hypervisor driver</h1>
- <ul id="toc"></ul>
- <p>
- The libvirt VMware ESX driver can manage VMware ESX/ESXi 3.5/4.x/5.x and
- VMware GSX 2.0, also called VMware Server 2.0, and possibly later
- versions. <span class="since">Since 0.8.3</span> the driver can also
- connect to a VMware vCenter 2.5/4.x/5.x (VPX).
- </p>
-
- <h2><a id="project">Project Links</a></h2>
-
- <ul>
- <li>
- The <a href="https://www.vmware.com/">VMware ESX and GSX</a>
- hypervisors
- </li>
- </ul>
-
- <h2><a id="prereq">Deployment pre-requisites</a></h2>
- <p>
- None. Any out-of-the-box installation of VPX/ESX(i)/GSX should work. No
- preparations are required on the server side, no libvirtd must be
- installed on the ESX server. The driver uses version 2.5 of the remote,
- SOAP based
- <a href="https://www.vmware.com/support/developer/vc-sdk/visdk25pubs/ReferenceGuide/">
- VMware Virtual Infrastructure API</a> (VI API) to communicate with the
- ESX server, like the VMware Virtual Infrastructure Client (VI client)
- does. Since version 4.0 this API is called
- <a href="https://www.vmware.com/support/developer/vc-sdk/visdk400pubs/ReferenceGuide/">
- VMware vSphere API</a>.
- </p>
-
- <h2><a id="uri">Connections to the VMware ESX driver</a></h2>
- <p>
- Some example remote connection URIs for the driver are:
- </p>
-<pre>
-vpx://example-vcenter.com/dc1/srv1 (VPX over HTTPS, select ESX server 'srv1' in datacenter 'dc1')
-esx://example-esx.com (ESX over HTTPS)
-gsx://example-gsx.com (GSX over HTTPS)
-esx://example-esx.com/?transport=http (ESX over HTTP)
-esx://example-esx.com/?no_verify=1 (ESX over HTTPS, but doesn't verify the server's SSL certificate)
-</pre>
- <p>
- <strong>Note</strong>: In contrast to other drivers, the ESX driver is
- a client-side-only driver. It connects to the ESX server using HTTP(S).
- Therefore, the <a href="remote.html">remote transport mechanism</a>
- provided by the remote driver and libvirtd will not work, and you
- cannot use URIs like <code>esx+ssh://example.com</code>.
- </p>
-
-
- <h3><a id="uriformat">URI Format</a></h3>
- <p>
- URIs have this general form (<code>[...]</code> marks an optional part).
- </p>
-<pre>
-type://[username@]hostname[:port]/[[folder/...]datacenter/[folder/...][cluster/]server][?extraparameters]
-</pre>
- <p>
- The <code>type://</code> is either <code>esx://</code> or
- <code>gsx://</code> or <code>vpx://</code> <span class="since">since 0.8.3</span>.
- The driver selects the default port depending on the <code>type://</code>.
- For <code>esx://</code> and <code>vpx://</code> the default HTTPS port
- is 443, for <code>gsx://</code> it is 8333.
- If the port parameter is given, it overrides the default port.
- </p>
- <p>
- A <code>vpx://</code> connection is currently restricted to a single
- ESX server. This might be relaxed in the future. The path part of the
- URI is used to specify the datacenter and the ESX server in it. If the
- ESX server is part of a cluster then the cluster has to be specified too.
- </p>
- <p>
- An example: ESX server <code>example-esx.com</code> is managed by
- vCenter <code>example-vcenter.com</code> and part of cluster
- <code>cluster1</code>. This cluster is part of datacenter <code>dc1</code>.
- </p>
-<pre>
-vpx://example-vcenter.com/dc1/cluster1/example-esx.com
-</pre>
- <p>
- Datacenters and clusters can be organized in folders, those have to be
- specified as well. The driver can handle folders
- <span class="since">since 0.9.7</span>.
- </p>
-<pre>
-vpx://example-vcenter.com/folder1/dc1/folder2/example-esx.com
-</pre>
-
-
- <h4><a id="extraparams">Extra parameters</a></h4>
- <p>
- Extra parameters can be added to a URI as part of the query string
- (the part following <code>?</code>). A single parameter is formed by a
- <code>name=value</code> pair. Multiple parameters are separated by
- <code>&</code>.
- </p>
-<pre>
-?<span style="color: #E50000">no_verify=1</span>&<span style="color: #00B200">auto_answer=1</span>&<span style="color: #0000E5">proxy=socks://example-proxy.com:23456</span>
-</pre>
- <p>
- The driver understands the extra parameters shown below.
- </p>
- <table class="top_table">
- <tr>
- <th>Name</th>
- <th>Values</th>
- <th>Meaning</th>
- </tr>
- <tr>
- <td>
- <code>transport</code>
- </td>
- <td>
- <code>http</code> or <code>https</code>
- </td>
- <td>
- Overrides the default HTTPS transport. For <code>esx://</code>
- and <code>vpx://</code> the default HTTP port is 80, for
- <code>gsx://</code> it is 8222.
- </td>
- </tr>
- <tr>
- <td>
- <code>vcenter</code>
- </td>
- <td>
- Hostname of a VMware vCenter or <code>*</code>
- </td>
- <td>
- In order to perform a migration the driver needs to know the
- VMware vCenter for the ESX server. If set to <code>*</code>,
- the driver connects to the vCenter known to the ESX server.
- This parameter in useful when connecting to an ESX server only.
- </td>
- </tr>
- <tr>
- <td>
- <code>no_verify</code>
- </td>
- <td>
- <code>0</code> or <code>1</code>
- </td>
- <td>
- If set to 1, this disables libcurl client checks of the server's
- SSL certificate. The default value is 0. See the
- <a href="#certificates">Certificates for HTTPS</a> section for
- details.
- </td>
- </tr>
- <tr>
- <td>
- <code>auto_answer</code>
- </td>
- <td>
- <code>0</code> or <code>1</code>
- </td>
- <td>
- If set to 1, the driver answers all
- <a href="#questions">questions</a> with the default answer.
- If set to 0, questions are reported as errors. The default
- value is 0. <span class="since">Since 0.7.5</span>.
- </td>
- </tr>
- <tr>
- <td>
- <code>proxy</code>
- </td>
- <td>
- <code>[type://]hostname[:port]</code>
- </td>
- <td>
- Allows to specify a proxy for HTTP and HTTPS communication.
- <span class="since">Since 0.8.2</span>.
- The optional <code>type</code> part may be one of:
- <code>http</code>, <code>socks</code>, <code>socks4</code>,
- <code>socks4a</code> or <code>socks5</code>. The default is
- <code>http</code> and <code>socks</code> is synonymous for
- <code>socks5</code>. The optional <code>port</code> allows to
- override the default port 1080.
- </td>
- </tr>
- </table>
-
-
- <h3><a id="auth">Authentication</a></h3>
- <p>
- In order to perform any useful operation the driver needs to log into
- the ESX server. Therefore, only <code>virConnectOpenAuth</code> can be
- used to connect to an ESX server, <code>virConnectOpen</code> and
- <code>virConnectOpenReadOnly</code> don't work.
- To log into an ESX server or vCenter the driver will request
- credentials using the callback passed to the
- <code>virConnectOpenAuth</code> function. The driver passes the
- hostname as challenge parameter to the callback. This enables the
- callback to distinguish between requests for ESX server and vCenter.
- </p>
- <p>
- <strong>Note</strong>: During the ongoing driver development, testing
- is done using an unrestricted <code>root</code> account. Problems may
- occur if you use a restricted account. Detailed testing with restricted
- accounts has not been done yet.
- </p>
-
-
- <h3><a id="certificates">Certificates for HTTPS</a></h3>
- <p>
- By default the ESX driver uses HTTPS to communicate with an ESX server.
- Proper HTTPS communication requires correctly configured SSL
- certificates. This certificates are different from the ones libvirt
- uses for <a href="remote.html">secure communication over TLS</a> to a
- libvirtd one a remote server.
- </p>
- <p>
- By default the driver tries to verify the server's SSL certificate
- using the CA certificate pool installed on your client computer. With
- an out-of-the-box installed ESX server this won't work, because a newly
- installed ESX server uses auto-generated self-signed certificates.
- Those are signed by a CA certificate that is typically not known to your
- client computer and libvirt will report an error like this one:
- </p>
-<pre>
-error: internal error curl_easy_perform() returned an error: Peer certificate cannot be authenticated with known CA certificates (60)
-</pre>
- <p>
- Where are two ways to solve this problem:
- </p>
- <ul>
- <li>
- Use the <code>no_verify=1</code> <a href="#extraparams">extra parameter</a>
- to disable server certificate verification.
- </li>
- <li>
- Generate new SSL certificates signed by a CA known to your client
- computer and replace the original ones on your ESX server. See the
- section <i>Replace a Default Certificate with a CA-Signed Certificate</i>
- in the <a href="https://www.vmware.com/pdf/vsphere4/r40/vsp_40_esx_server_config.pdf">ESX Configuration Guide</a>
- </li>
- </ul>
-
-
- <h3><a id="connproblems">Connection problems</a></h3>
- <p>
- There are also other causes for connection problems than the
- <a href="#certificates">HTTPS certificate</a> related ones.
- </p>
- <ul>
- <li>
- As stated before the ESX driver doesn't need the
- <a href="remote.html">remote transport mechanism</a>
- provided by the remote driver and libvirtd, nor does the ESX driver
- support it. Therefore, using an URI including a transport in the
- scheme won't work. Only <a href="#uriformat">URIs as described</a>
- are supported by the ESX driver. Here's a collection of possible
- error messages:
-<pre>
-$ virsh -c esx+tcp://example.com/
-error: unable to connect to libvirtd at 'example.com': Connection refused
-</pre>
-<pre>
-$ virsh -c esx+tls://example.com/
-error: Cannot access CA certificate '/etc/pki/CA/cacert.pem': No such file or directory
-</pre>
-<pre>
-$ virsh -c esx+ssh://example.com/
-error: cannot recv data: ssh: connect to host example.com port 22: Connection refused
-</pre>
-<pre>
-$ virsh -c esx+ssh://example.com/
-error: cannot recv data: Resource temporarily unavailable
-</pre>
- </li>
- <li>
- <span class="since">Since 0.7.0</span> libvirt contains the ESX
- driver. Earlier versions of libvirt will report a misleading error
- about missing certificates when you try to connect to an ESX server.
-<pre>
-$ virsh -c esx://example.com/
-error: Cannot access CA certificate '/etc/pki/CA/cacert.pem': No such file or directory
-</pre>
- <p>
- Don't let this error message confuse you. Setting up certificates
- as described on the <a href="remote.html#Remote_certificates">remote transport mechanism</a> page
- does not help, as this is not a certificate related problem.
- </p>
- <p>
- To fix this problem you need to update your libvirt to 0.7.0 or newer.
- You may also see this error when you use a libvirt version that
- contains the ESX driver but you or your distro disabled the ESX
- driver during compilation. <span class="since">Since 0.8.3</span>
- the error message has been improved in this case:
- </p>
-<pre>
-$ virsh -c esx://example.com/
-error: invalid argument in libvirt was built without the 'esx' driver
-</pre>
- </li>
- </ul>
-
-
- <h2><a id="questions">Questions blocking tasks</a></h2>
- <p>
- Some methods of the VI API start tasks, for example
- <code>PowerOnVM_Task()</code>. Such tasks may be blocked by questions
- if the ESX server detects an issue with the domain that requires user
- interaction. The ESX driver cannot prompt the user to answer a
- question, libvirt doesn't have an API for something like this.
- </p>
- <p>
- The VI API provides the <code>AnswerVM()</code> method to
- programmatically answer a questions. So the driver has two options
- how to handle such a situation: either answer the questions with the
- default answer or report the question as an error and cancel the
- blocked task if possible. The
- <a href="#uriformat"><code>auto_answer</code></a> query parameter
- controls the answering behavior.
- </p>
-
-
- <h2><a id="xmlspecial">Specialities in the domain XML config</a></h2>
- <p>
- There are several specialities in the domain XML config for ESX domains.
- </p>
-
- <h3><a id="restrictions">Restrictions</a></h3>
- <p>
- There are some restrictions for some values of the domain XML config.
- The driver will complain if this restrictions are violated.
- </p>
- <ul>
- <li>
- Memory size has to be a multiple of 4096
- </li>
- <li>
- Number of virtual CPU has to be 1 or a multiple of 2.
- <span class="since">Since 4.10.0</span> any number of vCPUs is
- supported.
- </li>
- <li>
- Valid MAC address prefixes are <code>00:0c:29</code> and
- <code>00:50:56</code>. <span class="since">Since 0.7.6</span>
- arbitrary <a href="#macaddresses">MAC addresses</a> are supported.
- </li>
- </ul>
-
-
- <h3><a id="datastore">Datastore references</a></h3>
- <p>
- Storage is managed in datastores. VMware uses a special path format to
- reference files in a datastore. Basically, the datastore name is put
- into squared braces in front of the path.
- </p>
-<pre>
-[datastore] directory/filename
-</pre>
- <p>
- To define a new domain the driver converts the domain XML into a
- VMware VMX file and uploads it to a datastore known to the ESX server.
- Because multiple datastores may be known to an ESX server the driver
- needs to decide to which datastore the VMX file should be uploaded.
- The driver deduces this information from the path of the source of the
- first file-based harddisk listed in the domain XML.
- </p>
-
-
- <h3><a id="macaddresses">MAC addresses</a></h3>
- <p>
- VMware has registered two MAC address prefixes for domains:
- <code>00:0c:29</code> and <code>00:50:56</code>. These prefixes are
- split into ranges for different purposes.
- </p>
- <table class="top_table">
- <tr>
- <th>Range</th>
- <th>Purpose</th>
- </tr>
- <tr>
- <td>
- <code>00:0c:29:00:00:00</code> - <code>00:0c:29:ff:ff:ff</code>
- </td>
- <td>
- An ESX server autogenerates MAC addresses from this range if
- the VMX file doesn't contain a MAC address when trying to start
- a domain.
- </td>
- </tr>
- <tr>
- <td>
- <code>00:50:56:00:00:00</code> - <code>00:50:56:3f:ff:ff</code>
- </td>
- <td>
- MAC addresses from this range can by manually assigned by the
- user in the VI client.
- </td>
- </tr>
- <tr>
- <td>
- <code>00:50:56:80:00:00</code> - <code>00:50:56:bf:ff:ff</code>
- </td>
- <td>
- A VI client autogenerates MAC addresses from this range for
- newly defined domains.
- </td>
- </tr>
- </table>
- <p>
- The VMX files generated by the ESX driver always contain a MAC address,
- because libvirt generates a random one if an interface element in the
- domain XML file lacks a MAC address.
- <span class="since">Since 0.7.6</span> the ESX driver sets the prefix
- for generated MAC addresses to <code>00:0c:29</code>. Before 0.7.6
- the <code>00:50:56</code> prefix was used. Sometimes this resulted in
- the generation of out-of-range MAC address that were rejected by the
- ESX server.
- </p>
- <p>
- Also <span class="since">since 0.7.6</span> every MAC address outside
- this ranges can be used. For such MAC addresses the ESX server-side
- check is disabled in the VMX file to stop the ESX server from rejecting
- out-of-predefined-range MAC addresses.
- </p>
-<pre>
-ethernet0.checkMACAddress = "false"
-</pre>
- <p>
- <span class="since">Since 6.6.0</span>, one can force libvirt to keep the
- provided MAC address when it's in the reserved VMware range by adding a
- <code>type="static"</code> attribute to the <code><mac/></code> element.
- Note that this attribute is useless if the provided MAC address is outside of
- the reserved VMWare ranges.
- </p>
-
-
- <h3><a id="hardware">Available hardware</a></h3>
- <p>
- VMware ESX supports different models of SCSI controllers and network
- cards.
- </p>
-
- <h4>SCSI controller models</h4>
- <dl>
- <dt><code>auto</code></dt>
- <dd>
- This isn't an actual controller model. If specified the ESX driver
- tries to detect the SCSI controller model referenced in the
- <code>.vmdk</code> file and use it. Autodetection fails when a
- SCSI controller has multiple disks attached and the SCSI controller
- models referenced in the <code>.vmdk</code> files are inconsistent.
- <span class="since">Since 0.8.3</span>
- </dd>
- <dt><code>buslogic</code></dt>
- <dd>
- BusLogic SCSI controller for older guests.
- </dd>
- <dt><code>lsilogic</code></dt>
- <dd>
- LSI Logic SCSI controller for recent guests.
- </dd>
- <dt><code>lsisas1068</code></dt>
- <dd>
- LSI Logic SAS 1068 controller. <span class="since">Since 0.8.0</span>
- </dd>
- <dt><code>vmpvscsi</code></dt>
- <dd>
- Special VMware Paravirtual SCSI controller, requires VMware tools inside
- the guest. See <a href="https://kb.vmware.com/kb/1010398">VMware KB1010398</a>
- for details. <span class="since">Since 0.8.3</span>
- </dd>
- </dl>
- <p>
- Here a domain XML snippet:
- </p>
-<pre>
-...
-<disk type='file' device='disk'>
- <source file='[local-storage] Fedora11/Fedora11.vmdk'/>
- <target dev='sda' bus='scsi'/>
- <address type='drive' controller='0' bus='0' unit='0'/>
-</disk>
-<controller type='scsi' index='0' model='<strong>lsilogic</strong>'/>
-...
-</pre>
- <p>
- The controller element is supported <span class="since">since 0.8.2</span>.
- Prior to this <code><driver name='lsilogic'/></code> was abused to
- specify the SCSI controller model. This attribute usage is deprecated now.
- </p>
-<pre>
-...
-<disk type='file' device='disk'>
- <driver name='<strong>lsilogic</strong>'/>
- <source file='[local-storage] Fedora11/Fedora11.vmdk'/>
- <target dev='sda' bus='scsi'/>
-</disk>
-...
-</pre>
-
-
- <h4>Network card models</h4>
- <dl>
- <dt><code>vlance</code></dt>
- <dd>
- AMD PCnet32 network card for older guests.
- </dd>
- <dt><code>vmxnet</code>, <code>vmxnet2</code>, <code>vmxnet3</code></dt>
- <dd>
- Special VMware VMXnet network card, requires VMware tools inside
- the guest. See <a href="https://kb.vmware.com/kb/1001805">VMware KB1001805</a>
- for details.
- </dd>
- <dt><code>e1000</code></dt>
- <dd>
- Intel E1000 network card for recent guests.
- </dd>
- </dl>
- <p>
- Here a domain XML snippet:
- </p>
-<pre>
-...
-<interface type='bridge'>
- <mac address='00:50:56:25:48:c7'/>
- <source bridge='VM Network'/>
- <model type='<strong>e1000</strong>'/>
-</interface>
-...
-</pre>
-
-
- <h2><a id="importexport">Import and export of domain XML configs</a></h2>
- <p>
- The ESX driver currently supports a native config format known as
- <code>vmware-vmx</code> to handle VMware VMX configs.
- </p>
-
-
- <h3><a id="xmlimport">Converting from VMware VMX config to domain XML config</a></h3>
- <p>
- The <code>virsh domxml-from-native</code> provides a way to convert an
- existing VMware VMX config into a domain XML config that can then be
- used by libvirt.
- </p>
-<pre>
-$ cat > demo.vmx << EOF
-#!/usr/bin/vmware
-config.version = "8"
-virtualHW.version = "4"
-floppy0.present = "false"
-nvram = "Fedora11.nvram"
-deploymentPlatform = "windows"
-virtualHW.productCompatibility = "hosted"
-tools.upgrade.policy = "useGlobal"
-powerType.powerOff = "default"
-powerType.powerOn = "default"
-powerType.suspend = "default"
-powerType.reset = "default"
-displayName = "Fedora11"
-extendedConfigFile = "Fedora11.vmxf"
-scsi0.present = "true"
-scsi0.sharedBus = "none"
-scsi0.virtualDev = "lsilogic"
-memsize = "1024"
-scsi0:0.present = "true"
-scsi0:0.fileName = "/vmfs/volumes/498076b2-02796c1a-ef5b-000ae484a6a3/Fedora11/Fedora11.vmdk"
-scsi0:0.deviceType = "scsi-hardDisk"
-ide0:0.present = "true"
-ide0:0.clientDevice = "true"
-ide0:0.deviceType = "cdrom-raw"
-ide0:0.startConnected = "false"
-ethernet0.present = "true"
-ethernet0.networkName = "VM Network"
-ethernet0.addressType = "vpx"
-ethernet0.generatedAddress = "00:50:56:91:48:c7"
-chipset.onlineStandby = "false"
-guestOSAltName = "Red Hat Enterprise Linux 5 (32-Bit)"
-guestOS = "rhel5"
-uuid.bios = "50 11 5e 16 9b dc 49 d7-f1 71 53 c4 d7 f9 17 10"
-snapshot.action = "keep"
-sched.cpu.min = "0"
-sched.cpu.units = "mhz"
-sched.cpu.shares = "normal"
-sched.mem.minsize = "0"
-sched.mem.shares = "normal"
-toolScripts.afterPowerOn = "true"
-toolScripts.afterResume = "true"
-toolScripts.beforeSuspend = "true"
-toolScripts.beforePowerOff = "true"
-scsi0:0.redo = ""
-tools.syncTime = "false"
-uuid.location = "56 4d b5 06 a2 bd fb eb-ae 86 f7 d8 49 27 d0 c4"
-sched.cpu.max = "unlimited"
-sched.swap.derivedName = "/vmfs/volumes/498076b2-02796c1a-ef5b-000ae484a6a3/Fedora11/Fedora11-7de040d8.vswp"
-tools.remindInstall = "TRUE"
-EOF
-
-$ virsh -c esx://example.com domxml-from-native vmware-vmx demo.vmx
-Enter username for example.com [root]:
-Enter root password for example.com:
-<domain type='vmware'>
- <name>Fedora11</name>
- <uuid>50115e16-9bdc-49d7-f171-53c4d7f91710</uuid>
- <memory>1048576</memory>
- <currentMemory>1048576</currentMemory>
- <vcpu>1</vcpu>
- <os>
- <type arch='i686'>hvm</type>
- </os>
- <clock offset='utc'/>
- <on_poweroff>destroy</on_poweroff>
- <on_reboot>restart</on_reboot>
- <on_crash>destroy</on_crash>
- <devices>
- <disk type='file' device='disk'>
- <source file='[local-storage] Fedora11/Fedora11.vmdk'/>
- <target dev='sda' bus='scsi'/>
- <address type='drive' controller='0' bus='0' unit='0'/>
- </disk>
- <controller type='scsi' index='0' model='lsilogic'/>
- <interface type='bridge'>
- <mac address='00:50:56:91:48:c7'/>
- <source bridge='VM Network'/>
- </interface>
- </devices>
-</domain>
-</pre>
-
-
- <h3><a id="xmlexport">Converting from domain XML config to VMware VMX config</a></h3>
- <p>
- The <code>virsh domxml-to-native</code> provides a way to convert a
- domain XML config into a VMware VMX config.
- </p>
-<pre>
-$ cat > demo.xml << EOF
-<domain type='vmware'>
- <name>Fedora11</name>
- <uuid>50115e16-9bdc-49d7-f171-53c4d7f91710</uuid>
- <memory>1048576</memory>
- <currentMemory>1048576</currentMemory>
- <vcpu>1</vcpu>
- <os>
- <type arch='x86_64'>hvm</type>
- </os>
- <devices>
- <disk type='file' device='disk'>
- <source file='[local-storage] Fedora11/Fedora11.vmdk'/>
- <target dev='sda' bus='scsi'/>
- <address type='drive' controller='0' bus='0' unit='0'/>
- </disk>
- <controller type='scsi' index='0' model='lsilogic'/>
- <interface type='bridge'>
- <mac address='00:50:56:25:48:c7'/>
- <source bridge='VM Network'/>
- </interface>
- </devices>
-</domain>
-EOF
-
-$ virsh -c esx://example.com domxml-to-native vmware-vmx demo.xml
-Enter username for example.com [root]:
-Enter root password for example.com:
-config.version = "8"
-virtualHW.version = "4"
-guestOS = "other-64"
-uuid.bios = "50 11 5e 16 9b dc 49 d7-f1 71 53 c4 d7 f9 17 10"
-displayName = "Fedora11"
-memsize = "1024"
-numvcpus = "1"
-scsi0.present = "true"
-scsi0.virtualDev = "lsilogic"
-scsi0:0.present = "true"
-scsi0:0.deviceType = "scsi-hardDisk"
-scsi0:0.fileName = "/vmfs/volumes/local-storage/Fedora11/Fedora11.vmdk"
-ethernet0.present = "true"
-ethernet0.networkName = "VM Network"
-ethernet0.connectionType = "bridged"
-ethernet0.addressType = "static"
-ethernet0.address = "00:50:56:25:48:C7"
-</pre>
-
-
- <h2><a id="xmlconfig">Example domain XML configs</a></h2>
-
- <h3>Fedora11 on x86_64</h3>
-<pre>
-<domain type='vmware'>
- <name>Fedora11</name>
- <uuid>50115e16-9bdc-49d7-f171-53c4d7f91710</uuid>
- <memory>1048576</memory>
- <currentMemory>1048576</currentMemory>
- <vcpu>1</vcpu>
- <os>
- <type arch='x86_64'>hvm</type>
- </os>
- <devices>
- <disk type='file' device='disk'>
- <source file='[local-storage] Fedora11/Fedora11.vmdk'/>
- <target dev='sda' bus='scsi'/>
- <address type='drive' controller='0' bus='0' unit='0'/>
- </disk>
- <controller type='scsi' index='0'/>
- <interface type='bridge'>
- <mac address='00:50:56:25:48:c7'/>
- <source bridge='VM Network'/>
- </interface>
- </devices>
-</domain>
-</pre>
-
-
- <h2><a id="migration">Migration</a></h2>
- <p>
- A migration cannot be initiated on an ESX server directly, a VMware
- vCenter is necessary for this. The <code>vcenter</code> query
- parameter must be set either to the hostname or IP address of the
- vCenter managing the ESX server or to <code>*</code>. Setting it
- to <code>*</code> causes the driver to connect to the vCenter known to
- the ESX server. If the ESX server is not managed by a vCenter an error
- is reported.
- </p>
-<pre>
-esx://example.com/?vcenter=example-vcenter.com
-</pre>
- <p>
- Here's an example how to migrate the domain <code>Fedora11</code> from
- ESX server <code>example-src.com</code> to ESX server
- <code>example-dst.com</code> implicitly involving vCenter
- <code>example-vcenter.com</code> using <code>virsh</code>.
- </p>
-<pre>
-$ virsh -c esx://example-src.com/?vcenter=* migrate Fedora11 esx://example-dst.com/?vcenter=*
-Enter username for example-src.com [root]:
-Enter root password for example-src.com:
-Enter username for example-vcenter.com [administrator]:
-Enter administrator password for example-vcenter.com:
-Enter username for example-dst.com [root]:
-Enter root password for example-dst.com:
-Enter username for example-vcenter.com [administrator]:
-Enter administrator password for example-vcenter.com:
-</pre>
- <p>
- <span class="since">Since 0.8.3</span> you can directly connect to a vCenter.
- This simplifies migration a bit. Here's the same migration as above but
- using <code>vpx://</code> connections and assuming both ESX server are in
- datacenter <code>dc1</code> and aren't part of a cluster.
- </p>
-<pre>
-$ virsh -c vpx://example-vcenter.com/dc1/example-src.com migrate Fedora11 vpx://example-vcenter.com/dc1/example-dst.com
-Enter username for example-vcenter.com [administrator]:
-Enter administrator password for example-vcenter.com:
-Enter username for example-vcenter.com [administrator]:
-Enter administrator password for example-vcenter.com:
-</pre>
-
-
- <h2><a id="scheduler">Scheduler configuration</a></h2>
- <p>
- The driver exposes the ESX CPU scheduler. The parameters listed below
- are available to control the scheduler.
- </p>
- <dl>
- <dt><code>reservation</code></dt>
- <dd>
- The amount of CPU resource in MHz that is guaranteed to be
- available to the domain. Valid values are 0 and greater.
- </dd>
- <dt><code>limit</code></dt>
- <dd>
- The CPU utilization of the domain will be
- limited to this value in MHz, even if more CPU resources are
- available. If the limit is set to -1, the CPU utilization of the
- domain is unlimited. If the limit is not set to -1, it must be
- greater than or equal to the reservation.
- </dd>
- <dt><code>shares</code></dt>
- <dd>
- Shares are used to determine relative CPU
- allocation between domains. In general, a domain with more shares
- gets proportionally more of the CPU resource. Valid values are 0
- and greater. The special values -1, -2 and -3 represent the
- predefined shares level <code>low</code>, <code>normal</code> and
- <code>high</code>.
- </dd>
- </dl>
-
-
- <h2><a id="tools">VMware tools</a></h2>
- <p>
- Some actions require installed VMware tools. If the VMware tools are
- not installed in the guest and one of the actions below is to be
- performed the ESX server raises an error and the driver reports it.
- </p>
- <ul>
- <li>
- <code>virDomainGetHostname</code>
- </li>
- <li>
- <code>virDomainInterfaceAddresses</code> (only for the
- <code>VIR_DOMAIN_INTERFACE_ADDRESSES_SRC_AGENT</code> source)
- </li>
- <li>
- <code>virDomainReboot</code>
- </li>
- <li>
- <code>virDomainShutdown</code>
- </li>
- </ul>
-
-
- <h2><a id="links">Links</a></h2>
- <ul>
- <li>
- <a href="https://www.vmware.com/support/developer/vc-sdk/">
- VMware vSphere Web Services SDK Documentation
- </a>
- </li>
- <li>
- <a href="https://www.vmware.com/pdf/esx3_memory.pdf">
- The Role of Memory in VMware ESX Server 3
- </a>
- </li>
- <li>
- <a href="https://www.sanbarrow.com/vmx.html">
- VMware VMX config parameters
- </a>
- </li>
- <li>
- <a href="https://www.vmware.com/pdf/vsp_4_pvscsi_perf.pdf">
- VMware ESX 4.0 PVSCSI Storage Performance
- </a>
- </li>
- </ul>
-</body></html>
diff --git a/docs/drvesx.rst b/docs/drvesx.rst
new file mode 100644
index 0000000000..7b35492d21
--- /dev/null
+++ b/docs/drvesx.rst
@@ -0,0 +1,681 @@
+.. role:: since
+
+============================
+VMware ESX hypervisor driver
+============================
+
+.. contents::
+
+The libvirt VMware ESX driver can manage VMware ESX/ESXi 3.5/4.x/5.x and VMware
+GSX 2.0, also called VMware Server 2.0, and possibly later versions.
+:since:`Since 0.8.3` the driver can also connect to a VMware vCenter 2.5/4.x/5.x
+(VPX).
+
+Project Links
+-------------
+
+- The `VMware ESX and GSX <https://www.vmware.com/>`__ hypervisors
+
+Deployment pre-requisites
+-------------------------
+
+None. Any out-of-the-box installation of VPX/ESX(i)/GSX should work. No
+preparations are required on the server side, no libvirtd must be installed on
+the ESX server. The driver uses version 2.5 of the remote, SOAP based `VMware
+Virtual Infrastructure
+API <https://www.vmware.com/support/developer/vc-sdk/visdk25pubs/ReferenceGuide/>`__
+(VI API) to communicate with the ESX server, like the VMware Virtual
+Infrastructure Client (VI client) does. Since version 4.0 this API is called
+`VMware vSphere
+API <https://www.vmware.com/support/developer/vc-sdk/visdk400pubs/ReferenceGuide/>`__.
+
+Connections to the VMware ESX driver
+------------------------------------
+
+Some example remote connection URIs for the driver are:
+
+::
+
+ vpx://example-vcenter.com/dc1/srv1 (VPX over HTTPS, select ESX server 'srv1' in datacenter 'dc1')
+ esx://example-esx.com (ESX over HTTPS)
+ gsx://example-gsx.com (GSX over HTTPS)
+ esx://example-esx.com/?transport=http (ESX over HTTP)
+ esx://example-esx.com/?no_verify=1 (ESX over HTTPS, but doesn't verify the server's SSL certificate)
+
+**Note**: In contrast to other drivers, the ESX driver is a client-side-only
+driver. It connects to the ESX server using HTTP(S). Therefore, the `remote
+transport mechanism <remote.html>`__ provided by the remote driver and libvirtd
+will not work, and you cannot use URIs like ``esx+ssh://example.com``.
+
+URI Format
+~~~~~~~~~~
+
+URIs have this general form (``[...]`` marks an optional part).
+
+::
+
+ type://[username@]hostname[:port]/[[folder/...]datacenter/[folder/...][cluster/]server][?extraparameters]
+
+The ``type://`` is either ``esx://`` or ``gsx://`` or ``vpx://`` :since:`since
+0.8.3` . The driver selects the default port depending on the ``type://``. For
+``esx://`` and ``vpx://`` the default HTTPS port is 443, for ``gsx://`` it is
+8333. If the port parameter is given, it overrides the default port.
+
+A ``vpx://`` connection is currently restricted to a single ESX server. This
+might be relaxed in the future. The path part of the URI is used to specify the
+datacenter and the ESX server in it. If the ESX server is part of a cluster then
+the cluster has to be specified too.
+
+An example: ESX server ``example-esx.com`` is managed by vCenter
+``example-vcenter.com`` and part of cluster ``cluster1``. This cluster is part
+of datacenter ``dc1``.
+
+::
+
+ vpx://example-vcenter.com/dc1/cluster1/example-esx.com
+
+Datacenters and clusters can be organized in folders, those have to be specified
+as well. The driver can handle folders :since:`since 0.9.7` .
+
+::
+
+ vpx://example-vcenter.com/folder1/dc1/folder2/example-esx.com
+
+Extra parameters
+^^^^^^^^^^^^^^^^
+
+Extra parameters can be added to a URI as part of the query string (the part
+following ``?``). A single parameter is formed by a ``name=value`` pair.
+Multiple parameters are separated by ``&``.
+
+::
+
+ ?no_verify=1&auto_answer=1&proxy=socks://example-proxy.com:23456
+
+The driver understands the extra parameters shown below.
+
++-----------------+-----------------------------+-----------------------------+
+| Name | Values | Meaning |
++=================+=============================+=============================+
+| ``transport`` | ``http`` or ``https`` | Overrides the default HTTPS |
+| | | transport. For ``esx://`` |
+| | | and ``vpx://`` the default |
+| | | HTTP port is 80, for |
+| | | ``gsx://`` it is 8222. |
++-----------------+-----------------------------+-----------------------------+
+| ``vcenter`` | Hostname of a VMware | In order to perform a |
+| | vCenter or ``*`` | migration the driver needs |
+| | | to know the VMware vCenter |
+| | | for the ESX server. If set |
+| | | to ``*``, the driver |
+| | | connects to the vCenter |
+| | | known to the ESX server. |
+| | | This parameter in useful |
+| | | when connecting to an ESX |
+| | | server only. |
++-----------------+-----------------------------+-----------------------------+
+| ``no_verify`` | ``0`` or ``1`` | If set to 1, this disables |
+| | | libcurl client checks of |
+| | | the server's SSL |
+| | | certificate. The default |
+| | | value is 0. See the |
+| | | `Certificates for |
+| | | HTTPS <#certificates>`__ |
+| | | section for details. |
++-----------------+-----------------------------+-----------------------------+
+| ``auto_answer`` | ``0`` or ``1`` | If set to 1, the driver |
+| | | answers all |
+| | | `questions <#questions>`__ |
+| | | with the default answer. If |
+| | | set to 0, questions are |
+| | | reported as errors. The |
+| | | default value is 0. |
+| | | :since:`Since 0.7.5` . |
++-----------------+-----------------------------+-----------------------------+
+| ``proxy`` | [type://]hostname[:port] | Allows to specify a proxy |
+| | | for HTTP and HTTPS |
+| | | communication. |
+| | | :since:`Since 0.8.2` . The |
+| | | optional ``type`` part may |
+| | | be one of: ``http``, |
+| | | ``socks``, ``socks4``, |
+| | | ``socks4a`` or ``socks5``. |
+| | | The default is ``http`` and |
+| | | ``socks`` is synonymous for |
+| | | ``socks5``. The optional |
+| | | ``port`` allows to override |
+| | | the default port 1080. |
++-----------------+-----------------------------+-----------------------------+
+
+Authentication
+~~~~~~~~~~~~~~
+
+In order to perform any useful operation the driver needs to log into the ESX
+server. Therefore, only ``virConnectOpenAuth`` can be used to connect to an ESX
+server, ``virConnectOpen`` and ``virConnectOpenReadOnly`` don't work. To log
+into an ESX server or vCenter the driver will request credentials using the
+callback passed to the ``virConnectOpenAuth`` function. The driver passes the
+hostname as challenge parameter to the callback. This enables the callback to
+distinguish between requests for ESX server and vCenter.
+
+**Note**: During the ongoing driver development, testing is done using an
+unrestricted ``root`` account. Problems may occur if you use a restricted
+account. Detailed testing with restricted accounts has not been done yet.
+
+Certificates for HTTPS
+~~~~~~~~~~~~~~~~~~~~~~
+
+By default the ESX driver uses HTTPS to communicate with an ESX server. Proper
+HTTPS communication requires correctly configured SSL certificates. This
+certificates are different from the ones libvirt uses for `secure communication
+over TLS <remote.html>`__ to a libvirtd one a remote server.
+
+By default the driver tries to verify the server's SSL certificate using the CA
+certificate pool installed on your client computer. With an out-of-the-box
+installed ESX server this won't work, because a newly installed ESX server uses
+auto-generated self-signed certificates. Those are signed by a CA certificate
+that is typically not known to your client computer and libvirt will report an
+error like this one:
+
+::
+
+ error: internal error curl_easy_perform() returned an error: Peer certificate cannot be authenticated with known CA certificates (60)
+
+Where are two ways to solve this problem:
+
+- Use the ``no_verify=1`` `extra parameter <#extraparams>`__ to disable server
+ certificate verification.
+- Generate new SSL certificates signed by a CA known to your client computer
+ and replace the original ones on your ESX server. See the section *Replace a
+ Default Certificate with a CA-Signed Certificate* in the `ESX Configuration
+ Guide <https://www.vmware.com/pdf/vsphere4/r40/vsp_40_esx_server_config.pdf>`__
+
+Connection problems
+~~~~~~~~~~~~~~~~~~~
+
+There are also other causes for connection problems than the `HTTPS
+certificate <#certificates>`__ related ones.
+
+- As stated before the ESX driver doesn't need the `remote transport
+ mechanism <remote.html>`__ provided by the remote driver and libvirtd, nor
+ does the ESX driver support it. Therefore, using an URI including a transport
+ in the scheme won't work. Only `URIs as described <#uriformat>`__ are
+ supported by the ESX driver. Here's a collection of possible error messages:
+
+ ::
+
+ $ virsh -c esx+tcp://example.com/
+ error: unable to connect to libvirtd at 'example.com': Connection refused
+
+ ::
+
+ $ virsh -c esx+tls://example.com/
+ error: Cannot access CA certificate '/etc/pki/CA/cacert.pem': No such file or directory
+
+ ::
+
+ $ virsh -c esx+ssh://example.com/
+ error: cannot recv data: ssh: connect to host example.com port 22: Connection refused
+
+ ::
+
+ $ virsh -c esx+ssh://example.com/
+ error: cannot recv data: Resource temporarily unavailable
+
+- :since:`Since 0.7.0` libvirt contains the ESX driver. Earlier versions of
+ libvirt will report a misleading error about missing certificates when you
+ try to connect to an ESX server.
+
+ ::
+
+ $ virsh -c esx://example.com/
+ error: Cannot access CA certificate '/etc/pki/CA/cacert.pem': No such file or directory
+
+ Don't let this error message confuse you. Setting up certificates as
+ described on the `remote transport
+ mechanism <remote.html#Remote_certificates>`__ page does not help, as this is
+ not a certificate related problem.
+
+ To fix this problem you need to update your libvirt to 0.7.0 or newer. You
+ may also see this error when you use a libvirt version that contains the ESX
+ driver but you or your distro disabled the ESX driver during compilation.
+ :since:`Since 0.8.3` the error message has been improved in this case:
+
+ ::
+
+ $ virsh -c esx://example.com/
+ error: invalid argument in libvirt was built without the 'esx' driver
+
+Questions blocking tasks
+------------------------
+
+Some methods of the VI API start tasks, for example ``PowerOnVM_Task()``. Such
+tasks may be blocked by questions if the ESX server detects an issue with the
+domain that requires user interaction. The ESX driver cannot prompt the user to
+answer a question, libvirt doesn't have an API for something like this.
+
+The VI API provides the ``AnswerVM()`` method to programmatically answer a
+questions. So the driver has two options how to handle such a situation: either
+answer the questions with the default answer or report the question as an error
+and cancel the blocked task if possible. The `auto_answer <#uriformat>`__ query
+parameter controls the answering behavior.
+
+Specialities in the domain XML config
+-------------------------------------
+
+There are several specialities in the domain XML config for ESX domains.
+
+Restrictions
+~~~~~~~~~~~~
+
+There are some restrictions for some values of the domain XML config. The driver
+will complain if this restrictions are violated.
+
+- Memory size has to be a multiple of 4096
+- Number of virtual CPU has to be 1 or a multiple of 2. :since:`Since 4.10.0`
+ any number of vCPUs is supported.
+- Valid MAC address prefixes are ``00:0c:29`` and ``00:50:56``. :since:`Since
+ 0.7.6` arbitrary `MAC addresses <#macaddresses>`__ are supported.
+
+Datastore references
+~~~~~~~~~~~~~~~~~~~~
+
+Storage is managed in datastores. VMware uses a special path format to reference
+files in a datastore. Basically, the datastore name is put into squared braces
+in front of the path.
+
+::
+
+ [datastore] directory/filename
+
+To define a new domain the driver converts the domain XML into a VMware VMX file
+and uploads it to a datastore known to the ESX server. Because multiple
+datastores may be known to an ESX server the driver needs to decide to which
+datastore the VMX file should be uploaded. The driver deduces this information
+from the path of the source of the first file-based harddisk listed in the
+domain XML.
+
+MAC addresses
+~~~~~~~~~~~~~
+
+VMware has registered two MAC address prefixes for domains: ``00:0c:29`` and
+``00:50:56``. These prefixes are split into ranges for different purposes.
+
++--------------------------------------+--------------------------------------+
+| Range | Purpose |
++======================================+======================================+
+| ``00:0c:29:00:00:00`` - | An ESX server autogenerates MAC |
+| ``00:0c:29:ff:ff:ff`` | addresses from this range if the VMX |
+| | file doesn't contain a MAC address |
+| | when trying to start a domain. |
++--------------------------------------+--------------------------------------+
+| ``00:50:56:00:00:00`` - | MAC addresses from this range can by |
+| ``00:50:56:3f:ff:ff`` | manually assigned by the user in the |
+| | VI client. |
++--------------------------------------+--------------------------------------+
+| ``00:50:56:80:00:00`` - | A VI client autogenerates MAC |
+| ``00:50:56:bf:ff:ff`` | addresses from this range for newly |
+| | defined domains. |
++--------------------------------------+--------------------------------------+
+
+The VMX files generated by the ESX driver always contain a MAC address, because
+libvirt generates a random one if an interface element in the domain XML file
+lacks a MAC address. :since:`Since 0.7.6` the ESX driver sets the prefix for
+generated MAC addresses to ``00:0c:29``. Before 0.7.6 the ``00:50:56`` prefix
+was used. Sometimes this resulted in the generation of out-of-range MAC address
+that were rejected by the ESX server.
+
+Also :since:`since 0.7.6` every MAC address outside this ranges can be used. For
+such MAC addresses the ESX server-side check is disabled in the VMX file to stop
+the ESX server from rejecting out-of-predefined-range MAC addresses.
+
+::
+
+ ethernet0.checkMACAddress = "false"
+
+:since:`Since 6.6.0` , one can force libvirt to keep the provided MAC address
+when it's in the reserved VMware range by adding a ``type="static"`` attribute
+to the ``<mac/>`` element. Note that this attribute is useless if the provided
+MAC address is outside of the reserved VMWare ranges.
+
+Available hardware
+~~~~~~~~~~~~~~~~~~
+
+VMware ESX supports different models of SCSI controllers and network cards.
+
+SCSI controller models
+^^^^^^^^^^^^^^^^^^^^^^
+
+``auto``
+ This isn't an actual controller model. If specified the ESX driver tries to
+ detect the SCSI controller model referenced in the ``.vmdk`` file and use it.
+ Autodetection fails when a SCSI controller has multiple disks attached and
+ the SCSI controller models referenced in the ``.vmdk`` files are
+ inconsistent. :since:`Since 0.8.3`
+``buslogic``
+ BusLogic SCSI controller for older guests.
+``lsilogic``
+ LSI Logic SCSI controller for recent guests.
+``lsisas1068``
+ LSI Logic SAS 1068 controller. :since:`Since 0.8.0`
+``vmpvscsi``
+ Special VMware Paravirtual SCSI controller, requires VMware tools inside the
+ guest. See `VMware KB1010398 <https://kb.vmware.com/kb/1010398>`__ for
+ details. :since:`Since 0.8.3`
+
+Here a domain XML snippet:
+
+::
+
+ ...
+ <disk type='file' device='disk'>
+ <source file='[local-storage] Fedora11/Fedora11.vmdk'/>
+ <target dev='sda' bus='scsi'/>
+ <address type='drive' controller='0' bus='0' unit='0'/>
+ </disk>
+ <controller type='scsi' index='0' model='lsilogic'/>
+ ...
+
+The controller element is supported :since:`since 0.8.2` . Prior to this
+``<driver name='lsilogic'/>`` was abused to specify the SCSI controller model.
+This attribute usage is deprecated now.
+
+::
+
+ ...
+ <disk type='file' device='disk'>
+ <driver name='lsilogic'/>
+ <source file='[local-storage] Fedora11/Fedora11.vmdk'/>
+ <target dev='sda' bus='scsi'/>
+ </disk>
+ ...
+
+Network card models
+^^^^^^^^^^^^^^^^^^^
+
+``vlance``
+ AMD PCnet32 network card for older guests.
+``vmxnet``, ``vmxnet2``, ``vmxnet3``
+ Special VMware VMXnet network card, requires VMware tools inside the guest.
+ See `VMware KB1001805 <https://kb.vmware.com/kb/1001805>`__ for details.
+``e1000``
+ Intel E1000 network card for recent guests.
+
+Here a domain XML snippet:
+
+::
+
+ ...
+ <interface type='bridge'>
+ <mac address='00:50:56:25:48:c7'/>
+ <source bridge='VM Network'/>
+ <model type='e1000'/>
+ </interface>
+ ...
+
+Import and export of domain XML configs
+---------------------------------------
+
+The ESX driver currently supports a native config format known as ``vmware-vmx``
+to handle VMware VMX configs.
+
+Converting from VMware VMX config to domain XML config
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``virsh domxml-from-native`` provides a way to convert an existing VMware
+VMX config into a domain XML config that can then be used by libvirt.
+
+::
+
+ $ cat > demo.vmx << EOF
+ #!/usr/bin/vmware
+ config.version = "8"
+ virtualHW.version = "4"
+ floppy0.present = "false"
+ nvram = "Fedora11.nvram"
+ deploymentPlatform = "windows"
+ virtualHW.productCompatibility = "hosted"
+ tools.upgrade.policy = "useGlobal"
+ powerType.powerOff = "default"
+ powerType.powerOn = "default"
+ powerType.suspend = "default"
+ powerType.reset = "default"
+ displayName = "Fedora11"
+ extendedConfigFile = "Fedora11.vmxf"
+ scsi0.present = "true"
+ scsi0.sharedBus = "none"
+ scsi0.virtualDev = "lsilogic"
+ memsize = "1024"
+ scsi0:0.present = "true"
+ scsi0:0.fileName = "/vmfs/volumes/498076b2-02796c1a-ef5b-000ae484a6a3/Fedora11/Fedora11.vmdk"
+ scsi0:0.deviceType = "scsi-hardDisk"
+ ide0:0.present = "true"
+ ide0:0.clientDevice = "true"
+ ide0:0.deviceType = "cdrom-raw"
+ ide0:0.startConnected = "false"
+ ethernet0.present = "true"
+ ethernet0.networkName = "VM Network"
+ ethernet0.addressType = "vpx"
+ ethernet0.generatedAddress = "00:50:56:91:48:c7"
+ chipset.onlineStandby = "false"
+ guestOSAltName = "Red Hat Enterprise Linux 5 (32-Bit)"
+ guestOS = "rhel5"
+ uuid.bios = "50 11 5e 16 9b dc 49 d7-f1 71 53 c4 d7 f9 17 10"
+ snapshot.action = "keep"
+ sched.cpu.min = "0"
+ sched.cpu.units = "mhz"
+ sched.cpu.shares = "normal"
+ sched.mem.minsize = "0"
+ sched.mem.shares = "normal"
+ toolScripts.afterPowerOn = "true"
+ toolScripts.afterResume = "true"
+ toolScripts.beforeSuspend = "true"
+ toolScripts.beforePowerOff = "true"
+ scsi0:0.redo = ""
+ tools.syncTime = "false"
+ uuid.location = "56 4d b5 06 a2 bd fb eb-ae 86 f7 d8 49 27 d0 c4"
+ sched.cpu.max = "unlimited"
+ sched.swap.derivedName = "/vmfs/volumes/498076b2-02796c1a-ef5b-000ae484a6a3/Fedora11/Fedora11-7de040d8.vswp"
+ tools.remindInstall = "TRUE"
+ EOF
+
+ $ virsh -c esx://example.com domxml-from-native vmware-vmx demo.vmx
+ Enter username for example.com [root]:
+ Enter root password for example.com:
+ <domain type='vmware'>
+ <name>Fedora11</name>
+ <uuid>50115e16-9bdc-49d7-f171-53c4d7f91710</uuid>
+ <memory>1048576</memory>
+ <currentMemory>1048576</currentMemory>
+ <vcpu>1</vcpu>
+ <os>
+ <type arch='i686'>hvm</type>
+ </os>
+ <clock offset='utc'/>
+ <on_poweroff>destroy</on_poweroff>
+ <on_reboot>restart</on_reboot>
+ <on_crash>destroy</on_crash>
+ <devices>
+ <disk type='file' device='disk'>
+ <source file='[local-storage] Fedora11/Fedora11.vmdk'/>
+ <target dev='sda' bus='scsi'/>
+ <address type='drive' controller='0' bus='0' unit='0'/>
+ </disk>
+ <controller type='scsi' index='0' model='lsilogic'/>
+ <interface type='bridge'>
+ <mac address='00:50:56:91:48:c7'/>
+ <source bridge='VM Network'/>
+ </interface>
+ </devices>
+ </domain>
+
+Converting from domain XML config to VMware VMX config
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``virsh domxml-to-native`` provides a way to convert a domain XML config
+into a VMware VMX config.
+
+::
+
+ $ cat > demo.xml << EOF
+ <domain type='vmware'>
+ <name>Fedora11</name>
+ <uuid>50115e16-9bdc-49d7-f171-53c4d7f91710</uuid>
+ <memory>1048576</memory>
+ <currentMemory>1048576</currentMemory>
+ <vcpu>1</vcpu>
+ <os>
+ <type arch='x86_64'>hvm</type>
+ </os>
+ <devices>
+ <disk type='file' device='disk'>
+ <source file='[local-storage] Fedora11/Fedora11.vmdk'/>
+ <target dev='sda' bus='scsi'/>
+ <address type='drive' controller='0' bus='0' unit='0'/>
+ </disk>
+ <controller type='scsi' index='0' model='lsilogic'/>
+ <interface type='bridge'>
+ <mac address='00:50:56:25:48:c7'/>
+ <source bridge='VM Network'/>
+ </interface>
+ </devices>
+ </domain>
+ EOF
+
+ $ virsh -c esx://example.com domxml-to-native vmware-vmx demo.xml
+ Enter username for example.com [root]:
+ Enter root password for example.com:
+ config.version = "8"
+ virtualHW.version = "4"
+ guestOS = "other-64"
+ uuid.bios = "50 11 5e 16 9b dc 49 d7-f1 71 53 c4 d7 f9 17 10"
+ displayName = "Fedora11"
+ memsize = "1024"
+ numvcpus = "1"
+ scsi0.present = "true"
+ scsi0.virtualDev = "lsilogic"
+ scsi0:0.present = "true"
+ scsi0:0.deviceType = "scsi-hardDisk"
+ scsi0:0.fileName = "/vmfs/volumes/local-storage/Fedora11/Fedora11.vmdk"
+ ethernet0.present = "true"
+ ethernet0.networkName = "VM Network"
+ ethernet0.connectionType = "bridged"
+ ethernet0.addressType = "static"
+ ethernet0.address = "00:50:56:25:48:C7"
+
+Example domain XML configs
+--------------------------
+
+Fedora11 on x86_64
+~~~~~~~~~~~~~~~~~~
+
+::
+
+ <domain type='vmware'>
+ <name>Fedora11</name>
+ <uuid>50115e16-9bdc-49d7-f171-53c4d7f91710</uuid>
+ <memory>1048576</memory>
+ <currentMemory>1048576</currentMemory>
+ <vcpu>1</vcpu>
+ <os>
+ <type arch='x86_64'>hvm</type>
+ </os>
+ <devices>
+ <disk type='file' device='disk'>
+ <source file='[local-storage] Fedora11/Fedora11.vmdk'/>
+ <target dev='sda' bus='scsi'/>
+ <address type='drive' controller='0' bus='0' unit='0'/>
+ </disk>
+ <controller type='scsi' index='0'/>
+ <interface type='bridge'>
+ <mac address='00:50:56:25:48:c7'/>
+ <source bridge='VM Network'/>
+ </interface>
+ </devices>
+ </domain>
+
+Migration
+---------
+
+A migration cannot be initiated on an ESX server directly, a VMware vCenter is
+necessary for this. The ``vcenter`` query parameter must be set either to the
+hostname or IP address of the vCenter managing the ESX server or to ``*``.
+Setting it to ``*`` causes the driver to connect to the vCenter known to the ESX
+server. If the ESX server is not managed by a vCenter an error is reported.
+
+::
+
+ esx://example.com/?vcenter=example-vcenter.com
+
+Here's an example how to migrate the domain ``Fedora11`` from ESX server
+``example-src.com`` to ESX server ``example-dst.com`` implicitly involving
+vCenter ``example-vcenter.com`` using ``virsh``.
+
+::
+
+ $ virsh -c esx://example-src.com/?vcenter=* migrate Fedora11 esx://example-dst.com/?vcenter=*
+ Enter username for example-src.com [root]:
+ Enter root password for example-src.com:
+ Enter username for example-vcenter.com [administrator]:
+ Enter administrator password for example-vcenter.com:
+ Enter username for example-dst.com [root]:
+ Enter root password for example-dst.com:
+ Enter username for example-vcenter.com [administrator]:
+ Enter administrator password for example-vcenter.com:
+
+:since:`Since 0.8.3` you can directly connect to a vCenter. This simplifies
+migration a bit. Here's the same migration as above but using ``vpx://``
+connections and assuming both ESX server are in datacenter ``dc1`` and aren't
+part of a cluster.
+
+::
+
+ $ virsh -c vpx://example-vcenter.com/dc1/example-src.com migrate Fedora11 vpx://example-vcenter.com/dc1/example-dst.com
+ Enter username for example-vcenter.com [administrator]:
+ Enter administrator password for example-vcenter.com:
+ Enter username for example-vcenter.com [administrator]:
+ Enter administrator password for example-vcenter.com:
+
+Scheduler configuration
+-----------------------
+
+The driver exposes the ESX CPU scheduler. The parameters listed below are
+available to control the scheduler.
+
+``reservation``
+ The amount of CPU resource in MHz that is guaranteed to be available to the
+ domain. Valid values are 0 and greater.
+``limit``
+ The CPU utilization of the domain will be limited to this value in MHz, even
+ if more CPU resources are available. If the limit is set to -1, the CPU
+ utilization of the domain is unlimited. If the limit is not set to -1, it
+ must be greater than or equal to the reservation.
+``shares``
+ Shares are used to determine relative CPU allocation between domains. In
+ general, a domain with more shares gets proportionally more of the CPU
+ resource. Valid values are 0 and greater. The special values -1, -2 and -3
+ represent the predefined shares level ``low``, ``normal`` and ``high``.
+
+VMware tools
+------------
+
+Some actions require installed VMware tools. If the VMware tools are not
+installed in the guest and one of the actions below is to be performed the ESX
+server raises an error and the driver reports it.
+
+- ``virDomainGetHostname``
+- ``virDomainInterfaceAddresses`` (only for the
+ ``VIR_DOMAIN_INTERFACE_ADDRESSES_SRC_AGENT`` source)
+- ``virDomainReboot``
+- ``virDomainShutdown``
+
+Links
+-----
+
+- `VMware vSphere Web Services SDK
+ Documentation <https://www.vmware.com/support/developer/vc-sdk/>`__
+- `The Role of Memory in VMware ESX Server
+ 3 <https://www.vmware.com/pdf/esx3_memory.pdf>`__
+- `VMware VMX config parameters <https://www.sanbarrow.com/vmx.html>`__
+- `VMware ESX 4.0 PVSCSI Storage
+ Performance <https://www.vmware.com/pdf/vsp_4_pvscsi_perf.pdf>`__
diff --git a/docs/meson.build b/docs/meson.build
index a6c3077f25..0465c22274 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -22,7 +22,6 @@ docs_html_in_files = [
'csharp',
'dbus',
'docs',
- 'drvesx',
'drvhyperv',
'drvlxc',
'drvnodedev',
@@ -80,6 +79,7 @@ docs_rst_files = [
'drivers',
'drvbhyve',
'drvch',
+ 'drvesx',
'drvqemu',
'errors',
'formatbackup',
--
2.35.1
More information about the libvir-list
mailing list