From nobody Mon Feb 9 21:37:06 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) client-ip=170.10.129.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1648469471; cv=none; d=zohomail.com; s=zohoarc; b=PZCFeLawUMHc5JAZtf3w8x1jhXoeKdPYEWs93WomYpVNAX9m4pUJ1nNQpI5WxmDd4nKqXXH+xp1OgOILS+km7ctZfQO6YmmiRwo4vyq9wq/Ci9R5aVHrFd25d4oYUhObmx/Tn7mvPQRBeY2ontBuTpyaiv4XXISDNOoZilbj0ZU= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1648469471; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=vdcT5oKlxu/phH7+DmxPUPDLUNvEM+soz6CIToSjrp8=; b=UklWfCbA5nHsBYuM3bryQYjAOkahzNVBMyGhwAAJPPP3WqU79jllGKYR5hfaBX+p5ms5Q2Dr4W/svFx3fLph6VfVitOHhU+PIxH6MgRMMc0b0YyRw4RDwD7jkDppUjfgSC6UPFk6lFRll9Bvr0Z9ZWGnk7Pw3MzuWmE6LeTMutY= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by mx.zohomail.com with SMTPS id 1648469471505313.8274554592024; Mon, 28 Mar 2022 05:11:11 -0700 (PDT) Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-377-veD4Ix3TM7Gf3C4wgKJsbQ-1; Mon, 28 Mar 2022 08:10:56 -0400 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.rdu2.redhat.com [10.11.54.1]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 46271802803; Mon, 28 Mar 2022 12:10:53 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com [10.30.29.100]) by smtp.corp.redhat.com (Postfix) with ESMTP id 2AC4140CF8E8; Mon, 28 Mar 2022 12:10:53 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (localhost [IPv6:::1]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 4D6191940344; Mon, 28 Mar 2022 12:10:52 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.rdu2.redhat.com [10.11.54.7]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 67C2B1947BBF for ; Mon, 28 Mar 2022 12:10:51 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id 48F4C1457F13; Mon, 28 Mar 2022 12:10:51 +0000 (UTC) Received: from speedmetal.lan (unknown [10.40.208.35]) by smtp.corp.redhat.com (Postfix) with ESMTP id 6AF771427AE5 for ; Mon, 28 Mar 2022 12:10:50 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1648469470; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=vdcT5oKlxu/phH7+DmxPUPDLUNvEM+soz6CIToSjrp8=; b=fZOnAb/Pekb/gthF6KJqm3jY6j2yI56L2sbL/r5OVw5XVZr3UgvmaUHHu9z4oPczeTjNyN iJ4ZHlp+ZC8ofi1Ob0FiJ2K8uyvgIgeLE46Fw0AlmADMVXF945nuzb1gdc6DsIlhNO5fx5 Jh8zocuEnIYw7sj1pE/c370k1r0ZO1s= X-MC-Unique: veD4Ix3TM7Gf3C4wgKJsbQ-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 04/29] docs: Convert 'drvesx' page to rST Date: Mon, 28 Mar 2022 14:10:19 +0200 Message-Id: In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.85 on 10.11.54.7 X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libvir-list-bounces@redhat.com Sender: "libvir-list" X-Scanned-By: MIMEDefang 2.84 on 10.11.54.1 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1648469472232100002 Content-Type: text/plain; charset="utf-8"; x-default="true" Signed-off-by: Peter Krempa Reviewed-by: Erik Skultety --- 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 @@ - - - - -

VMware ESX hypervisor driver

-
    -

    - 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 0.8.3 the driver can = also - connect to a VMware vCenter 2.5/4.x/5.x (VPX). -

    - -

    Project Links

    - - - -

    Deployment pre-requisites

    -

    - None. Any out-of-the-box installation of VPX/ESX(i)/GSX should wor= k. 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 re= mote, - SOAP based - - VMware Virtual Infrastructure API (VI API) to communicate with= the - ESX server, like the VMware Virtual Infrastructure Client (VI clie= nt) - does. Since version 4.0 this API is called - - VMware vSphere API. -

    - -

    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=3Dhttp  (ESX over HTTP)
-esx://example-esx.com/?no_verify=3D1     (ESX over HTTPS, but doesn't veri=
fy the server's SSL certificate)
-
    -

    - Note: In contrast to other drivers, the ESX drive= r is - a client-side-only driver. It connects to the ESX server using HTT= P(S). - Therefore, the remote transport mechanism<= /a> - 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/...][clu=
ster/]server][?extraparameters]
-
    -

    - The type:// is either esx:// or - gsx:// or vpx:// s= ince 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 sing= le - 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 specifi= ed 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 dc= 1. -

    -
    -vpx://example-vcenter.com/dc1/cluster1/example-esx.com
-
    -

    - Datacenters and clusters can be organized in folders, those have t= o be - specified as well. The driver can handle folders - 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=3Dvalue pair. Multiple parameters are separated = by - &. -

    -
    -?no_verify=3D1&auto_answer=3D1&pro=
xy=3Dsocks://example-proxy.com:23456
-
    -

    - The driver understands the extra parameters shown below. -

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    NameValuesMeaning
    - 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 vCenter or * - - In order to perform a migration the driver needs to know t= he - 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 se= rver's - SSL certificate. The default value is 0. See the - Certificates for HTTPS secti= on for - details. -
    - auto_answer - - 0 or 1 - - If set to 1, the driver answers all - questions with the default answ= er. - If set to 0, questions are reported as errors. The default - value is 0. Since 0.7.5. -
    - proxy - - [type://]hostname[:port] - - Allows to specify a proxy for HTTP and HTTPS communication. - 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 i= nto - the ESX server. Therefore, only virConnectOpenAuth ca= n 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 vCente= r. -

    -

    - Note: During the ongoing driver development, test= ing - is done using an unrestricted root account. Problems = may - occur if you use a restricted account. Detailed testing with restr= icted - accounts has not been done yet. -

    - - -

    Certificates for HTTPS

    -

    - By default the ESX driver uses HTTPS to communicate with an ESX se= rver. - Proper HTTPS communication requires correctly configured SSL - certificates. This certificates are different from the ones libvirt - uses for secure communication over TLS= 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. W= ith - 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 t= o your - client computer and libvirt will report an error like this one: -

    -
    -error: internal error curl_easy_perform() returned an error: Peer certific=
ate cannot be authenticated with known CA certificates (60)
-
    -

    - Where are two ways to solve this problem: -

    -
      -
    • - Use the no_verify=3D1 ex= tra parameter - to disable server certificate verification. -
      • -
    • - Generate new SSL certificates signed by a CA known to your cli= ent - computer and replace the original ones on your ESX server. See= the - section Replace a Default Certificate with a CA-Signed Cert= ificate - in the ESX Configuration Guide -
      • -
    - - -

    Connection problems

    -

    - There are also other causes for connection problems than the - HTTPS certificate related ones. -

    -
      -
    • - As stated before the ESX driver doesn't need the - remote transport mechanism - provided by the remote driver and libvirtd, nor does the ESX d= river - support it. Therefore, using an URI including a transport in t= he - scheme won't work. Only URIs as describ= ed - are supported by the ESX driver. Here's a collection of possib= le - 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: Connect=
ion refused
-
      -
      -$ virsh -c esx+ssh://example.com/
-error: cannot recv data: Resource temporarily unavailable
-
      -
      • -
    • - Since 0.7.0 libvirt contains the = ESX - driver. Earlier versions of libvirt will report a misleading e= rror - about missing certificates when you try to connect to an ESX s= erver. -
      -$ 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 certi= ficates - as described on the remote transport mechanism page - does not help, as this is not a certificate related proble= m. -

      -

      - 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 th= e ESX - driver during compilation. 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 questi= ons - if the ESX server detects an issue with the domain that requires u= ser - 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 t= he - default answer or report the question as an error and cancel the - blocked task if possible. The - auto_answer query parameter - controls the answering behavior. -

    - - -

    Specialities in the domain XML config

    -

    - There are several specialities in the domain XML config for ESX do= mains. -

    - -

    Restrictions

    -

    - There are some restrictions for some values of the domain XML conf= ig. - 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 4.10.0 any number of vCPUs = is - supported. -
      • -
    • - Valid MAC address prefixes are 00:0c:29 and - 00:50:56. Since 0.7.6 - arbitrary MAC addresses are supp= orted. -
      • -
    - - -

    Datastore references

    -

    - Storage is managed in datastores. VMware uses a special path forma= t to - reference files in a datastore. Basically, the datastore name is p= ut - 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 ser= ver. - Because multiple datastores may be known to an ESX server the driv= er - 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. -

    - - - - - - - - - - - - - - - - - -
    RangePurpose
    - 00:0c:29:00:00:00 - 00:0c:29:ff:ff:ff - - 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. -
    - 00:50:56:00:00:00 - 00:50:56:3f:ff:ff - - MAC addresses from this range can by manually assigned by = the - user in the VI client. -
    - 00:50:56:80:00:00 - 00:50:56:bf:ff:ff - - A VI client autogenerates MAC addresses from this range for - newly defined domains. -
    -

    - The VMX files generated by the ESX driver always contain a MAC add= ress, - because libvirt generates a random one if an interface element in = the - domain XML file lacks a MAC address. - Since 0.7.6 the ESX driver sets the p= refix - 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 t= he - ESX server. -

    -

    - Also since 0.7.6 every MAC address ou= tside - 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 reje= cting - out-of-predefined-range MAC addresses. -

    -
    -ethernet0.checkMACAddress =3D "false"
-
    -

    - Since 6.6.0, one can force libvirt to= keep the - provided MAC address when it's in the reserved VMware range by add= ing a - type=3D"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 netwo= rk - cards. -

    - -

    SCSI controller models

    -
    -
    auto
    -
    - This isn't an actual controller model. If specified the ESX dr= iver - 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 contr= oller - models referenced in the .vmdk files are inconsis= tent. - 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 0.8= .0 -
    -
    vmpvscsi
    -
    - Special VMware Paravirtual SCSI controller, requires VMware to= ols inside - the guest. See VM= ware KB1010398 - for details. Since 0.8.3 -
    -
    -

    - Here a domain XML snippet: -

    -
    -...
-<disk type=3D'file' device=3D'disk'>
-  <source file=3D'[local-storage] Fedora11/Fedora11.vmdk'/>
-  <target dev=3D'sda' bus=3D'scsi'/>
-  <address type=3D'drive' controller=3D'0' bus=3D'0' unit=3D'0'/>
-</disk>
-<controller type=3D'scsi' index=3D'0' model=3D'lsilogic'/>
-...
-
    -

    - The controller element is supported since 0.= 8.2. - Prior to this <driver name=3D'lsilogic'/> was a= bused to - specify the SCSI controller model. This attribute usage is depreca= ted now. -

    -
    -...
-<disk type=3D'file' device=3D'disk'>
-  <driver name=3D'lsilogic'/>
-  <source file=3D'[local-storage] Fedora11/Fedora11.vmdk'/>
-  <target dev=3D'sda' bus=3D'scsi'/>
-</disk>
-...
-
    - - -

    Network card models

    -
    -
    vlance
    -
    - AMD PCnet32 network card for older guests. -
    -
    vmxnet, vmxnet2, vmxnet3
    -
    - Special VMware VMXnet network card, requires VMware tools insi= de - the guest. See VM= ware KB1001805 - for details. -
    -
    e1000
    -
    - Intel E1000 network card for recent guests. -
    -
    -

    - Here a domain XML snippet: -

    -
    -...
-<interface type=3D'bridge'>
-  <mac address=3D'00:50:56:25:48:c7'/>
-  <source bridge=3D'VM Network'/>
-  <model type=3D'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 XM= L config

    -

    - The virsh domxml-from-native provides a way to conver= t 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 =3D "8"
-virtualHW.version =3D "4"
-floppy0.present =3D "false"
-nvram =3D "Fedora11.nvram"
-deploymentPlatform =3D "windows"
-virtualHW.productCompatibility =3D "hosted"
-tools.upgrade.policy =3D "useGlobal"
-powerType.powerOff =3D "default"
-powerType.powerOn =3D "default"
-powerType.suspend =3D "default"
-powerType.reset =3D "default"
-displayName =3D "Fedora11"
-extendedConfigFile =3D "Fedora11.vmxf"
-scsi0.present =3D "true"
-scsi0.sharedBus =3D "none"
-scsi0.virtualDev =3D "lsilogic"
-memsize =3D "1024"
-scsi0:0.present =3D "true"
-scsi0:0.fileName =3D "/vmfs/volumes/498076b2-02796c1a-ef5b-000ae484a6a3/Fe=
dora11/Fedora11.vmdk"
-scsi0:0.deviceType =3D "scsi-hardDisk"
-ide0:0.present =3D "true"
-ide0:0.clientDevice =3D "true"
-ide0:0.deviceType =3D "cdrom-raw"
-ide0:0.startConnected =3D "false"
-ethernet0.present =3D "true"
-ethernet0.networkName =3D "VM Network"
-ethernet0.addressType =3D "vpx"
-ethernet0.generatedAddress =3D "00:50:56:91:48:c7"
-chipset.onlineStandby =3D "false"
-guestOSAltName =3D "Red Hat Enterprise Linux 5 (32-Bit)"
-guestOS =3D "rhel5"
-uuid.bios =3D "50 11 5e 16 9b dc 49 d7-f1 71 53 c4 d7 f9 17 10"
-snapshot.action =3D "keep"
-sched.cpu.min =3D "0"
-sched.cpu.units =3D "mhz"
-sched.cpu.shares =3D "normal"
-sched.mem.minsize =3D "0"
-sched.mem.shares =3D "normal"
-toolScripts.afterPowerOn =3D "true"
-toolScripts.afterResume =3D "true"
-toolScripts.beforeSuspend =3D "true"
-toolScripts.beforePowerOff =3D "true"
-scsi0:0.redo =3D ""
-tools.syncTime =3D "false"
-uuid.location =3D "56 4d b5 06 a2 bd fb eb-ae 86 f7 d8 49 27 d0 c4"
-sched.cpu.max =3D "unlimited"
-sched.swap.derivedName =3D "/vmfs/volumes/498076b2-02796c1a-ef5b-000ae484a=
6a3/Fedora11/Fedora11-7de040d8.vswp"
-tools.remindInstall =3D "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=3D'vmware'>
-  <name>Fedora11</name>
-  <uuid>50115e16-9bdc-49d7-f171-53c4d7f91710</uuid>
-  <memory>1048576</memory>
-  <currentMemory>1048576</currentMemory>
-  <vcpu>1</vcpu>
-  <os>
-    <type arch=3D'i686'>hvm</type>
-  </os>
-  <clock offset=3D'utc'/>
-  <on_poweroff>destroy</on_poweroff>
-  <on_reboot>restart</on_reboot>
-  <on_crash>destroy</on_crash>
-  <devices>
-    <disk type=3D'file' device=3D'disk'>
-      <source file=3D'[local-storage] Fedora11/Fedora11.vmdk'/>
-      <target dev=3D'sda' bus=3D'scsi'/>
-      <address type=3D'drive' controller=3D'0' bus=3D'0' unit=3D'0'/>
-    </disk>
-    <controller type=3D'scsi' index=3D'0' model=3D'lsilogic'/>
-    <interface type=3D'bridge'>
-      <mac address=3D'00:50:56:91:48:c7'/>
-      <source bridge=3D'VM Network'/>
-    </interface>
-  </devices>
-</domain>
-
    - - -

    Converting from domain XML config to VMware VM= X 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=3D'vmware'>
-  <name>Fedora11</name>
-  <uuid>50115e16-9bdc-49d7-f171-53c4d7f91710</uuid>
-  <memory>1048576</memory>
-  <currentMemory>1048576</currentMemory>
-  <vcpu>1</vcpu>
-  <os>
-    <type arch=3D'x86_64'>hvm</type>
-  </os>
-  <devices>
-    <disk type=3D'file' device=3D'disk'>
-      <source file=3D'[local-storage] Fedora11/Fedora11.vmdk'/>
-      <target dev=3D'sda' bus=3D'scsi'/>
-      <address type=3D'drive' controller=3D'0' bus=3D'0' unit=3D'0'/>
-    </disk>
-    <controller type=3D'scsi' index=3D'0' model=3D'lsilogic'/>
-    <interface type=3D'bridge'>
-      <mac address=3D'00:50:56:25:48:c7'/>
-      <source bridge=3D'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 =3D "8"
-virtualHW.version =3D "4"
-guestOS =3D "other-64"
-uuid.bios =3D "50 11 5e 16 9b dc 49 d7-f1 71 53 c4 d7 f9 17 10"
-displayName =3D "Fedora11"
-memsize =3D "1024"
-numvcpus =3D "1"
-scsi0.present =3D "true"
-scsi0.virtualDev =3D "lsilogic"
-scsi0:0.present =3D "true"
-scsi0:0.deviceType =3D "scsi-hardDisk"
-scsi0:0.fileName =3D "/vmfs/volumes/local-storage/Fedora11/Fedora11.vmdk"
-ethernet0.present =3D "true"
-ethernet0.networkName =3D "VM Network"
-ethernet0.connectionType =3D "bridged"
-ethernet0.addressType =3D "static"
-ethernet0.address =3D "00:50:56:25:48:C7"
-
    - - -

    Example domain XML configs

    - -

    Fedora11 on x86_64

    -
    -<domain type=3D'vmware'>
-  <name>Fedora11</name>
-  <uuid>50115e16-9bdc-49d7-f171-53c4d7f91710</uuid>
-  <memory>1048576</memory>
-  <currentMemory>1048576</currentMemory>
-  <vcpu>1</vcpu>
-  <os>
-    <type arch=3D'x86_64'>hvm</type>
-  </os>
-  <devices>
-    <disk type=3D'file' device=3D'disk'>
-      <source file=3D'[local-storage] Fedora11/Fedora11.vmdk'/>
-      <target dev=3D'sda' bus=3D'scsi'/>
-      <address type=3D'drive' controller=3D'0' bus=3D'0' unit=3D'0'/>
-    </disk>
-    <controller type=3D'scsi' index=3D'0'/>
-    <interface type=3D'bridge'>
-      <mac address=3D'00:50:56:25:48:c7'/>
-      <source bridge=3D'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 know= n to - the ESX server. If the ESX server is not managed by a vCenter an e= rror - is reported. -

    -
    -esx://example.com/?vcenter=3Dexample-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=3D* migrate Fedora11 esx://examp=
le-dst.com/?vcenter=3D*
-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 0.8.3 you can directly connect = to a vCenter. - This simplifies migration a bit. Here's the same migration as abov= e 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 be= low - 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 t= he - 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 sha= res - 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 a= re - 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

    - - 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 + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D +VMware ESX hypervisor driver +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D + +.. contents:: + +The libvirt VMware ESX driver can manage VMware ESX/ESXi 3.5/4.x/5.x and V= Mware +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 `__ 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 installe= d on +the ESX server. The driver uses version 2.5 of the remote, SOAP based `VMw= are +Virtual Infrastructure +API `__ +(VI API) to communicate with the ESX server, like the VMware Virtual +Infrastructure Client (VI client) does. Since version 4.0 this API is call= ed +`VMware vSphere +API `__. + +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 serv= er 'srv1' in datacenter 'dc1') + esx://example-esx.com (ESX over HTTPS) + gsx://example-gsx.com (GSX over HTTPS) + esx://example-esx.com/?transport=3Dhttp (ESX over HTTP) + esx://example-esx.com/?no_verify=3D1 (ESX over HTTPS, but doesn't v= erify the server's SSL certificate) + +**Note**: In contrast to other drivers, the ESX driver is a client-side-on= ly +driver. It connects to the ESX server using HTTP(S). Therefore, the `remote +transport mechanism `__ provided by the remote driver and lib= virtd +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:`s= ince +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. Th= is +might be relaxed in the future. The path part of the URI is used to specif= y the +datacenter and the ESX server in it. If the ESX server is part of a cluste= r 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 spe= cified +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 pa= rt +following ``?``). A single parameter is formed by a ``name=3Dvalue`` pair. +Multiple parameters are separated by ``&``. + +:: + + ?no_verify=3D1&auto_answer=3D1&proxy=3Dsocks://example-proxy.com:23456 + +The driver understands the extra parameters shown below. + ++-----------------+-----------------------------+-------------------------= ----+ +| Name | Values | Meaning = | ++=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D+ +| ``transport`` | ``http`` or ``https`` | Overrides the default HT= TPS | +| | | transport. For ``esx://`= ` | +| | | and ``vpx://`` the defau= lt | +| | | HTTP port is 80, for = | +| | | ``gsx://`` it is 8222. = | ++-----------------+-----------------------------+-------------------------= ----+ +| ``vcenter`` | Hostname of a VMware | In order to perform a = | +| | vCenter or ``*`` | migration the driver nee= ds | +| | | to know the VMware vCent= er | +| | | for the ESX server. If s= et | +| | | to ``*``, the driver = | +| | | connects to the vCenter = | +| | | known to the ESX server.= | +| | | This parameter in useful= | +| | | when connecting to an ES= X | +| | | server only. = | ++-----------------+-----------------------------+-------------------------= ----+ +| ``no_verify`` | ``0`` or ``1`` | If set to 1, this disabl= es | +| | | 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 prox= y | +| | | for HTTP and HTTPS = | +| | | communication. = | +| | | :since:`Since 0.8.2` . T= he | +| | | optional ``type`` part m= ay | +| | | be one of: ``http``, = | +| | | ``socks``, ``socks4``, = | +| | | ``socks4a`` or ``socks5`= `. | +| | | The default is ``http`` = and | +| | | ``socks`` is synonymous = for | +| | | ``socks5``. The optional= | +| | | ``port`` allows to overr= ide | +| | | 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 a= n ESX +server, ``virConnectOpen`` and ``virConnectOpenReadOnly`` don't work. To l= og +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. Pr= oper +HTTPS communication requires correctly configured SSL certificates. This +certificates are different from the ones libvirt uses for `secure communic= ation +over TLS `__ to a libvirtd one a remote server. + +By default the driver tries to verify the server's SSL certificate using t= he 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 certific= ate +that is typically not known to your client computer and libvirt will repor= t an +error like this one: + +:: + + error: internal error curl_easy_perform() returned an error: Peer certi= ficate cannot be authenticated with known CA certificates (60) + +Where are two ways to solve this problem: + +- Use the ``no_verify=3D1`` `extra parameter <#extraparams>`__ to disable= server + certificate verification. +- Generate new SSL certificates signed by a CA known to your client compu= ter + and replace the original ones on your ESX server. See the section *Repl= ace a + Default Certificate with a CA-Signed Certificate* in the `ESX Configura= tion + Guide `__ + +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 `__ provided by the remote driver and libvirtd, = nor + does the ESX driver support it. Therefore, using an URI including a tra= nsport + in the scheme won't work. Only `URIs as described <#uriformat>`__ are + supported by the ESX driver. Here's a collection of possible error mess= ages: + + :: + + $ virsh -c esx+tcp://example.com/ + error: unable to connect to libvirtd at 'example.com': Connection re= fused + + :: + + $ virsh -c esx+tls://example.com/ + error: Cannot access CA certificate '/etc/pki/CA/cacert.pem': No suc= h file or directory + + :: + + $ virsh -c esx+ssh://example.com/ + error: cannot recv data: ssh: connect to host example.com port 22: C= onnection 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 suc= h file or directory + + Don't let this error message confuse you. Setting up certificates as + described on the `remote transport + mechanism `__ page does not help, as t= his 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 th= e ESX + driver but you or your distro disabled the ESX driver during compilatio= n. + :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 us= er 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: e= ither +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.1= 0.0` + any number of vCPUs is supported. +- Valid MAC address prefixes are ``00:0c:29`` and ``00:50:56``. :since:`S= ince + 0.7.6` arbitrary `MAC addresses <#macaddresses>`__ are supported. + +Datastore references +~~~~~~~~~~~~~~~~~~~~ + +Storage is managed in datastores. VMware uses a special path format to ref= erence +files in a datastore. Basically, the datastore name is put into squared br= aces +in front of the path. + +:: + + [datastore] directory/filename + +To define a new domain the driver converts the domain XML into a VMware VM= X 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 whi= ch +datastore the VMX file should be uploaded. The driver deduces this informa= tion +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`` a= nd +``00:50:56``. These prefixes are split into ranges for different purposes. + ++--------------------------------------+----------------------------------= ----+ +| Range | Purpose = | ++=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D+ +| ``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 addres= s | +| | 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 new= ly | +| | defined domains. = | ++--------------------------------------+----------------------------------= ----+ + +The VMX files generated by the ESX driver always contain a MAC address, be= cause +libvirt generates a random one if an interface element in the domain XML f= ile +lacks a MAC address. :since:`Since 0.7.6` the ESX driver sets the prefix f= or +generated MAC addresses to ``00:0c:29``. Before 0.7.6 the ``00:50:56`` pre= fix +was used. Sometimes this resulted in the generation of out-of-range MAC ad= dress +that were rejected by the ESX server. + +Also :since:`since 0.7.6` every MAC address outside this ranges can be use= d. For +such MAC addresses the ESX server-side check is disabled in the VMX file t= o stop +the ESX server from rejecting out-of-predefined-range MAC addresses. + +:: + + ethernet0.checkMACAddress =3D "false" + +:since:`Since 6.6.0` , one can force libvirt to keep the provided MAC addr= ess +when it's in the reserved VMware range by adding a ``type=3D"static"`` att= ribute +to the ```` element. Note that this attribute is useless if the prov= ided +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 trie= s to + detect the SCSI controller model referenced in the ``.vmdk`` file and u= se 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 insid= e the + guest. See `VMware KB1010398 `__ for + details. :since:`Since 0.8.3` + +Here a domain XML snippet: + +:: + + ... + + + +
    + + + ... + +The controller element is supported :since:`since 0.8.2` . Prior to this +```` was abused to specify the SCSI controller = model. +This attribute usage is deprecated now. + +:: + + ... + + + + + + ... + +Network card models +^^^^^^^^^^^^^^^^^^^ + +``vlance`` + AMD PCnet32 network card for older guests. +``vmxnet``, ``vmxnet2``, ``vmxnet3`` + Special VMware VMXnet network card, requires VMware tools inside the gu= est. + See `VMware KB1001805 `__ for details. +``e1000`` + Intel E1000 network card for recent guests. + +Here a domain XML snippet: + +:: + + ... + + + + + + ... + +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 VMw= are +VMX config into a domain XML config that can then be used by libvirt. + +:: + + $ cat > demo.vmx << EOF + #!/usr/bin/vmware + config.version =3D "8" + virtualHW.version =3D "4" + floppy0.present =3D "false" + nvram =3D "Fedora11.nvram" + deploymentPlatform =3D "windows" + virtualHW.productCompatibility =3D "hosted" + tools.upgrade.policy =3D "useGlobal" + powerType.powerOff =3D "default" + powerType.powerOn =3D "default" + powerType.suspend =3D "default" + powerType.reset =3D "default" + displayName =3D "Fedora11" + extendedConfigFile =3D "Fedora11.vmxf" + scsi0.present =3D "true" + scsi0.sharedBus =3D "none" + scsi0.virtualDev =3D "lsilogic" + memsize =3D "1024" + scsi0:0.present =3D "true" + scsi0:0.fileName =3D "/vmfs/volumes/498076b2-02796c1a-ef5b-000ae484a6a3= /Fedora11/Fedora11.vmdk" + scsi0:0.deviceType =3D "scsi-hardDisk" + ide0:0.present =3D "true" + ide0:0.clientDevice =3D "true" + ide0:0.deviceType =3D "cdrom-raw" + ide0:0.startConnected =3D "false" + ethernet0.present =3D "true" + ethernet0.networkName =3D "VM Network" + ethernet0.addressType =3D "vpx" + ethernet0.generatedAddress =3D "00:50:56:91:48:c7" + chipset.onlineStandby =3D "false" + guestOSAltName =3D "Red Hat Enterprise Linux 5 (32-Bit)" + guestOS =3D "rhel5" + uuid.bios =3D "50 11 5e 16 9b dc 49 d7-f1 71 53 c4 d7 f9 17 10" + snapshot.action =3D "keep" + sched.cpu.min =3D "0" + sched.cpu.units =3D "mhz" + sched.cpu.shares =3D "normal" + sched.mem.minsize =3D "0" + sched.mem.shares =3D "normal" + toolScripts.afterPowerOn =3D "true" + toolScripts.afterResume =3D "true" + toolScripts.beforeSuspend =3D "true" + toolScripts.beforePowerOff =3D "true" + scsi0:0.redo =3D "" + tools.syncTime =3D "false" + uuid.location =3D "56 4d b5 06 a2 bd fb eb-ae 86 f7 d8 49 27 d0 c4" + sched.cpu.max =3D "unlimited" + sched.swap.derivedName =3D "/vmfs/volumes/498076b2-02796c1a-ef5b-000ae4= 84a6a3/Fedora11/Fedora11-7de040d8.vswp" + tools.remindInstall =3D "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: + + Fedora11 + 50115e16-9bdc-49d7-f171-53c4d7f91710 + 1048576 + 1048576 + 1 + + hvm + + + destroy + restart + destroy + + + + +
    + + + + + + + + + +Converting from domain XML config to VMware VMX config +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``virsh domxml-to-native`` provides a way to convert a domain XML conf= ig +into a VMware VMX config. + +:: + + $ cat > demo.xml << EOF + + Fedora11 + 50115e16-9bdc-49d7-f171-53c4d7f91710 + 1048576 + 1048576 + 1 + + hvm + + + + + +
    + + + + + + + + + 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 =3D "8" + virtualHW.version =3D "4" + guestOS =3D "other-64" + uuid.bios =3D "50 11 5e 16 9b dc 49 d7-f1 71 53 c4 d7 f9 17 10" + displayName =3D "Fedora11" + memsize =3D "1024" + numvcpus =3D "1" + scsi0.present =3D "true" + scsi0.virtualDev =3D "lsilogic" + scsi0:0.present =3D "true" + scsi0:0.deviceType =3D "scsi-hardDisk" + scsi0:0.fileName =3D "/vmfs/volumes/local-storage/Fedora11/Fedora11.vmd= k" + ethernet0.present =3D "true" + ethernet0.networkName =3D "VM Network" + ethernet0.connectionType =3D "bridged" + ethernet0.addressType =3D "static" + ethernet0.address =3D "00:50:56:25:48:C7" + +Example domain XML configs +-------------------------- + +Fedora11 on x86_64 +~~~~~~~~~~~~~~~~~~ + +:: + + + Fedora11 + 50115e16-9bdc-49d7-f171-53c4d7f91710 + 1048576 + 1048576 + 1 + + hvm + + + + + +
    + + + + + + + + + +Migration +--------- + +A migration cannot be initiated on an ESX server directly, a VMware vCente= r 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 t= he ESX +server. If the ESX server is not managed by a vCenter an error is reported. + +:: + + esx://example.com/?vcenter=3Dexample-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=3D* migrate Fedora11 esx://ex= ample-dst.com/?vcenter=3D* + 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 are= n't +part of a cluster. + +:: + + $ virsh -c vpx://example-vcenter.com/dc1/example-src.com migrate Fedora= 11 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 `__ +- `The Role of Memory in VMware ESX Server + 3 `__ +- `VMware VMX config parameters `__ +- `VMware ESX 4.0 PVSCSI Storage + Performance `__ 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 =3D [ 'csharp', 'dbus', 'docs', - 'drvesx', 'drvhyperv', 'drvlxc', 'drvnodedev', @@ -80,6 +79,7 @@ docs_rst_files =3D [ 'drivers', 'drvbhyve', 'drvch', + 'drvesx', 'drvqemu', 'errors', 'formatbackup', --=20 2.35.1