Signed-off-by: Peter Krempa <pkrempa@xxxxxxxxxx> --- 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
