VMware

 

VMware Virtual Infrastructure SDK 1.3 Release Notes


This page contains the Virtual Infrastructure SDK release notes for VMware VirtualCenter 1.2, 1.3, and 1.3.1. The 1.3.1 release notes are presented first, followed by the 1.3, and 1.2 release notes.


Virtual Infrastructure SDK Release Notes for VMware VirtualCenter 1.3.1


Bug Fixes Since the Previous Virtual Infrastructure SDK (VirtualCenter 1.3) Release
  1. Now, clients can create and delete filtered perf collectors without memory leaks.
  2. When running the CloneVM operation, clients can now create a scheduled task to specify the customization of the guest operating system.
  3. When using the PutUpdates operation to enable VMotion migrations, clients must still specify the change for the target "info/migrationEnabled" as the first change in the ChangeReq array. However, the Web service no longer abruptly shuts down if the wrong order is specified.

Virtual Infrastructure SDK Release Notes for VMware VirtualCenter 1.3


Changes Since the Previous Virtual Infrastructure SDK (VirtualCenter 1.2) Release

  • Clients can now enable or disable VMotion migrations on a host. Use the PutUpdates operation to modify the migrationEnabled field in the HostInfo datatype. In addition, the MigrationInfo datatype is now used by the Web service. Clients can use the PutUpdates operation to modify each field (network, ipAddress, and gateway) in this datatype. The subnet field is not used in this release.

    • To enable VMotion on a host:

      1. Set the migrationEnabled field in the HostInfo datatype to "true".
      2. Set the network, ipAddress, and gateway for the virtual machine that is migrating.

    • To disable VMotion on a host, set the migrationEnabled field in the HostInfo datatype to "false".

    Note: To enable VMotion migrations, clients must specify the change for the target "info/migrationEnabled" as the first change in the ChangeReq array. If this is not the first change, then the PutUpdates operation fails. (Changes for the other attributes may be placed in any order.

    For example, the following Java code snippet enables migration:

    Change ch1 = new Change();
    ch1.setTarget("info/migrationEnabled");
    ch1.setVal(new Boolean(true));
    ch1.setOp(ChangeOp.edit);

    Change ch2 = new Change();
    ch2.setTarget("info/migrationInfo/network");
    ch2.setVal("Adapter0 Network");
    ch2.setOp(ChangeOp.edit);

    Change ch3 = new Change();
    ch3.setTarget("info/migrationInfo/ipAddress");
    ch3.setVal("11.11.11.11");
    ch3.setOp(ChangeOp.edit);
    Change ch4 = new Change();
    ch4.setTarget("info/migrationInfo/gateway");
    ch4.setVal("11.11.11.1");
    ch4.setOp(ChangeOp.edit);

    ChangeReq upd = new ChangeReq();
    upd.setChange(new Change[] { ch1, ch3, ch2, ch4 });


    Similarly, the following Java code snippet disables migration:

    Change ch1 = new Change();
    ch1.setTarget("info/migrationEnabled");
    ch1.setVal(new Boolean(false));
    ch1.setOp(ChangeOp.edit);

    ChangeReq upd = new ChangeReq();
    upd.setChange(new Change[] { ch1 });

  • The Virtual Infrastructure SDK download package for VirtualCenter 1.3 includes updated samples, that illustrate how to handle socket timeout exceptions, when using the GetUpdates operation.

Bug Fixes Since the Previous Virtual Infrastructure SDK (VirtualCenter 1.2) Release
  1. The memory leak in the QueryPerfData and QueryPerfData2 operations has been fixed.
  2. The SOAP message response now matches the order in the WSDL schema for the PerfFilter datatype. Without this fix, the order of the elements in the SOAP response was different from the WSDL definition. Some tool kits were not handling this issue, and throwing an exception during the deserialization of the message.
  3. An http standards compliance issue regarding the case sensitivity of http header field names has been fixed.

Virtual Infrastructure SDK Release Notes for VMware VirtualCenter 1.2


Changes Since the Previous VMware SDK (VirtualCenter 1.1) Release

Note: For detailed information about these changes, refer to the Virtual Infrastructure SDK Programming Guide and the Virtual Infrastructure SDK Reference Guide.

  1. The four built-in perf collectors (hourly, daily, weekly, and monthly collectors) are now turned off by default.Clients can still query these perf collectors with the QueryPerfData andQueryPerfData2 operations, but their contents in the view hierarchy are not updated.

    In order to collect performance statistics, clients must now create filtered perf collectors. The creation of a filtered perf collector is shown in a Java sample called FilteredPerfMonitor, which is available in SDK/WebService/samples/java/sampleapp/src, under com/vmware/sample/PerformanceMonitoring.

    Invoke this sample by typing:

    runsamples.bat com.vmware.sample.PerformanceMonitoring.FilteredPerfMonitor <VMA URL> <username> <password> <src1path> <src2path>

    If you need to turn on the built-in perf collectors for any reason, do the following:
    1. Add the following to the <subject>
      vmaConfig.xml in C:\Documents and Settings\All Users\Application Data\VMware\VMware VirtualCenter\VMA.

      <periodicPerfRefreshEnable>true</periodicPerfRefreshEnable>
    2. Then restart the VMware VirtualCenter Webservice service from the Windows services control panel. In general, this is discouraged as it can place an undue load in a large environment because it polls every single host and virtual machine for performance statistics.

  2. Starting with this release, the vma.wsdl file can only be accessed by placing ?wsdl after the Web service URL; for example,https://localhost:8443?wsdl. The vma.wsdl file can no longer be accessed by the alternative path of /webservice/wsdl.

  3. A new operation, QueryPerfData2, is now available for getting additional performance statistics from hosts and virtual machines.

  4. The CloneVM operation now supports schema-based customization. The stubs for customization objects are automatically generated from vma.wsdl and the user does not have to pass raw XML to customize a virtual machine.

  5. The Web service API now supports the ability to create custom event collectors, in addition to the embedded event collectors in hosts and virtual machines.

  6. The Web service now supports GSX Server 3.1 hosts in addition to ESX Server 2.0.1, 2.1, 2.1.x and 2.5 hosts.

  7. The Web service now includes the SnapshotVM, ConsolidateVM, and RevertVM operations to manage snapshots on GSX Server 3.1 and redo logs on ESX Server 2.5 hosts.

  8. We have added support for raw disk mappings for ESX Server hosts.

  9. We have added samples in Perl using SOAP::Lite to the VMware SDK zip file.

  10. We have also added samples in Visual Basic .NET to the VMware SDK zip file.

  11. You can specify whether or not the Web serivce log file should be a single file, or rollover log files. If you choose rollover log files, then when each log file reaches its maximum size, logging starts in a new log file. Refer to the section on vmaConfig.xml in the Virtual Infrastructure SDK Programming Guide.

Bug Fixes Since the Previous VMware SDK (VirtualCenter 1.1) Release
  1. The StopVM operation with suspend = true and soft = true now works correctly.

  2. Stopping the VirtualCenter Web service through the Windows control panel sometimes resulted in a pop-up error dialog about pipe having ended.

  3. If the /Default Farm directory was removed from VirtualCenter, then creating a host in /host would sometimes fail.

  4. The ResolvePath operation was not checking user permissions.

  5. You can now use the SSL port with stubs generated by Apache Axis.

  6. If an incorrect user name or password was provided for the Web service to use to connect to VirtualCenter, then the error message that was returned was not very helpful. This has been fixed with the following:

    Browser Can't Connect to the Web Service

    If you are unable to connect to the Web service, first double-check your username and password and retry the request. If you see an XML document similar to the following, then check the Web service log file.

    - <env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    - <env:Body>
    - <env:Fault>
     <env:faultcode xmlns:ns="urn:vma1">ns:FaultInfo</env:faultcode>
      <env:faultstring>Service Unavailable</env:faultstring>
      <env:faultactor>vma</env:faultactor>
    - <env:detail>
    - <ns:FaultInfo xmlns:ns="urn:vma1">
      <kind>BadRequest</kind>
      <code>503</code>
      <info>Service Unavailable</info>
      </ns:FaultInfo>
      </env:detail>
      </env:Fault>
      </env:Body>
      </env:Envelope>

    Client Can't Connect to VirtualCenter

    When a client program has issues connecting to VirtualCenter, there are two typical causes: either the client can't connect to the Web service, or the Web service can't connect to VirtualCenter.

    Client Can't Connect to the Web Service

    If this is the problem, then the Web service returns a PermissionDenied fault for the Login operation. The client is using an invalid user name or password in the Login request. Choose a valid user name and password, and retry the Login request.

    In this case, nothing is logged in the Web service log file (by default, vma.txt), unless the /vcenter subject log level has been changed from its default value of "info" to verbose. If the log level is verbose, then the following error message is logged:

    Authentication of user <username> with VirtualCenter service on host <hostname>, port <port_number> failed: Bad username/password

    Web Service Can't Connect to VirtualCenter

    If this is the problem, then the Web service returns a BadRequest fault with error code 503 (ServiceUnavailable) for the Login operation. The Web service is in a bad or disconnected state. There are three possible causes: the Web service is unable to log into the VirtualCenter service, the VirtualCenter service is not running, or the VirtualCenter port number is incorrect. You must examine the Web service log file (by default, vma.txt), to determine the source of the problem.

    • If the VirtualCenter service is running, but the Web service is unable to log in (as a user with administrative privileges), then the following error message is logged.

      VirtualCenter web service failed to connect to VirtualCenter service on host <hostname>, port <port_number> as <administrator>: Bad username/password

      Configure the Web service with a valid user name and password (with administrative privileges) for the Web service to connect to VirtualCenter. Use the vma command-line program, as described in the section on Changing Web Service Options After Installation in the VMware VirtualCenter Users Manual.

    • If the VirtualCenter service is not running, then the following error message is logged.

      VirtualCenter web service failed to connect to VirtualCenter service on host <hostname>, port <port_number>: Connection refused

      1. Check the VirtualCenter service, and restart it.
      2. Stop, then restart the Web service. Refer to section titled Changing VMware Web Service Options After Installation in the VMware VirtualCenter Users Manual for detailed instructions.
    • If the Web service is using the incorrect port number to connect to VirtualCenter, then the following error message is logged.

      VirtualCenter web service failed to connect to VirtualCenter service on host <hostname>, port <port_number>: No connection could be made because the target machine actively refused it.

      1. Stop the Web service. Refer to section titled Changing VMware Web Service Options After Installation in the VMware VirtualCenter Users Manual for detailed instructions.
      2. Edit the vmaConfig.xml file with the correct VirtualCenter port number.
      3. Restart the Web service.
Known Issues and Bugs
  1. It may be possible to invoke the Delete, RunTask and EndTask operations even though the user has only Browse permission on the underlying object manipulated by the task, such as a virtual machine.

  2. There is an issue with running the MoveVM Java sample with stubs generated by IBM WSDK. The stub generator generates the name of the VirtualDiskDestination parameter with the name VirtualDiskDestination instead of disk. This error causes the conversion of the parameters to fail, because the Web service expects disk and the parameters name is wrong. (Unbounded elements in complexTypes that are Method parameter elements are not handled correctly.)

    To fix this problem, you need to edit the VmaBindingStub.java class file.

    If you are using the pre-built Java stubs contained in the VMware SDK package, then we have already edited the VmaBindingStub.java class file with this fix, and no change is required. However, if you are regenerating these stubs yourself, then complete the following steps.

    Note: The following procedure is also documented in its entirety in the Troubleshooting chapter of the Virtual Infrastructure SDK Programming Guide.

    1. Generate the stub files. Refer to the Virtual Infrastructure SDK Programming Guide.

    2. Search for the term _moveVMOperation in VmaBindingStub.java in the <client starting directory>\com\vmware\vma directory. There should be a ParameterDesc:

      new com.ibm.ws.webservices.engine.description.ParameterDesc (com.ibm.ws.webservices.engine.utils.QNameTable.createQName("urn:vma1", "VirtualDiskDestination"), com.ibm.ws.webservices.engine.description.ParameterDesc.IN, com.ibm.ws.webservices.engine.utils.QNameTable.createQName("urn:vma1", "VirtualDiskDestination"), com.vmware.vma.VirtualDiskDestination[].class, false, false),

    3. Change the mention of VirtualDiskDestination in the First createQName call in this line to disk. Do not change any other occurrences of VirtualDiskDestination in this file. This line should now resemble the following:

      new com.ibm.ws.webservices.engine.description.ParameterDesc (com.ibm.ws.webservices.engine.utils.QNameTable.createQName("urn:vma1", "disk"), com.ibm.ws.webservices.engine.description.ParameterDesc.IN, com.ibm.ws.webservices.engine.utils.QNameTable.createQName("urn:vma1", "VirtualDiskDestination"), com.vmware.vma.VirtualDiskDestination[].class, false, false),

    4. Recompile the files without regenerating the stubs.

  3. The SnapshotVM and RevertVM operations on a powered-off virtual machine on a GSX Server host can fail even though the operations appear to complete successfully. For GSX Server, we recommend that clients perform these operations only on powered-on virtual machines through the Web service interface.

  4. The Edit change operation is not supported on string values in this release. Clients cannot perform partial updates on a string. If the Edit change operation is called on a string, the result is similar to a Replace change operation, where the entire string is replaced.

  5. If your client application is connected to the Web service over an SSL connection, then you may get a java.netBindException when the client calls a SDK operation. If this happens, the client application should retry the SDK operation, after waiting for a reasonable duration of time.

  6. If a client application issues a SnapshotVM operation and then immediately issues a ConsolidateVM or RevertVM operation, the second operation may fail with a "No snapshot" error (because the first operation has not completed). A delay must be introduced before the second operation and possibly, the client may need to retry the second operation.