C Web Services API

Oracle VM Manager provides a Web services Application Programming Interface (API) to enable integration of third party products with Oracle VM Manager. You can use the API to perform any of the operations in Oracle VM Manager, for example, to create a server pool, add servers, and create virtual machines. You can use any language that supports Web services to access the API, for example Java or Python.

This Appendix describes the Oracle VM Manager Web services API and contains:

Web Services API
Creating a Web Service Client
Authentication and Security
Web Service Locations
Web Services

Web Services API

Oracle VM Manager acts as an administration platform for Oracle VM Servers connected on a network to direct actions to the virtual machines, virtual servers and the server pool. Oracle VM Manager provides the management environment for Oracle VM. A Web services API is available for Oracle VM Manager. The Oracle VM Manager Web services API architecture is shown in Figure C-1, "Oracle VM Manager Web Services API Architecture".

Figure C-1 Oracle VM Manager Web Services API Architecture

Description of "Figure C-1 Oracle VM Manager Web Services API Architecture"

The Oracle VM Manager API provides a complete set of interfaces to Oracle VM Manager. The Oracle VM Manager API is accessed through the Oracle VM Manager Web services API using the SOAP protocol.

The Oracle VM Manager Web service API provides all the operations necessary, including life-cycle operations, to monitor and manage virtual infrastructure components, like server pools, virtual servers, virtual machines, networks, storage, and so on.

The Oracle VM Manager Web services API is implemented as shown in Figure C-2, "Oracle VM Manager Web Services API Implementation".

Figure C-2 Oracle VM Manager Web Services API Implementation

Description of "Figure C-2 Oracle VM Manager Web Services API Implementation"

The Oracle VM Manager API is used by the Oracle VM Manager UI layer, and by the virtualization management component of Oracle Enterprise Manager. The Web services API can be used by Oracle applications as well as third party applications.

Creating a Web Service Client

You can use any programming language that supports Web services to create a Web services client. Most example code in this Chapter is written in Java and created using Oracle JDeveloper, although you can use the language and development tool of your choice.

To use Web services in Java, you can create SOAP messages directly, or generate proxy classes for each Web service. In Oracle JDeveloper, use the Web service WSDL URL to automatically generate proxy classes.

Creating a Proxy Class in Java

The examples given here use Oracle JDeveloper and the Java wsimport utility to create proxy classes in Java.

Using Oracle JDeveloper

To create a proxy class for an Oracle VM Manager Web service in Java using Oracle JDeveloper, use the Web service WSDL URL feature.

Example C-1 Retrieving a Server Pool by Name Using Oracle JDeveloper

An Oracle JDeveloper proxy class for retrieving a server pool using its name might look similar to:

public ServerPool getServerPoolByName(String poolName) throws Exception{
        String username = "myuser";
        String password = "mypassword";
        
        //ServerPoolServiceSoapHttpPortClient is generated by Jdeveloper.
        server.ServerPoolServiceSoapHttpPortClient myPort = 
           new server.ServerPoolServiceSoapHttpPortClient();
        myPort.setMaintainSession(true);
        myPort.setUsername(username);
        myPort.setPassword(password);
        ServerPool thePool = myPort.getServerPoolByName(poolName);
        return thePool;
    }

Example C-2 Importing a Guest Virtual Machine or Template Using Oracle JDeveloper

An Oracle JDeveloper proxy class for importing a guest virtual machine, or template, might look similar to:

/**
 * @param args
 */
public static void main(String[] args) {
    try {
        oracle.ovs.api.ResourceServiceSoapHttpPortClient myPort = new oracle.ovs.api.ResourceServiceSoapHttpPortClient();
        System.out.println("calling " + myPort.getEndpoint());
        
        /* External Template Importing **/
        VirtualMachineTemplate vmt = new VirtualMachineTemplate();
        /* set template name **/
        vmt.setImgName("MyTemplate");
        /* set download url **/
        vmt.setDownloadURL("http://example.com/OEL5");
        /* set proxy url(optional) **/
        vmt.setProxyURL("http://proxy.example.com:80");
        /* set vm username **/
        vmt.setVmUsername("myuser");
        /* set vm password **/
        vmt.setVmPassword("mypassword");
        /* set operating system type **/
        vmt.setOsType("Enterprise Linux 5");
        /* set description **/
        vmt.setDescription("My description.");
        /* start importing **/
        myPort.registerExternalTemplate("example.com", vmt);
        
        /* Internal Image Importing **/
        VirtualMachineImage vmi = new VirtualMachineImage();
        /* set vm name **/
        DiscoveredVirtualMachineImage[] unregisteredImages = myPort.getAllDiscoverableImages("example.com");
        /* find unregistered vm **/
        if (unregisteredImages.length > 0) {
            vmi.setImgName(unregisteredImages[0].getImgName());
        }
        else {
            return;
        }

        /* set vm username **/
        vmi.setVmUsername("myuser");
        /* set vm passwd **/
        vmi.setVmPassword("mypassword");
        /* set vnc password **/
        vmi.setVncPassword("mypassword");
        /* set operating system type **/
        vmi.setOsType("Enterprise Linux 4 64-bit");
        /* set description **/
        vmi.setDescription("My description.");
        /* start importing **/
        myPort.registerInternalImage("example.com", vmi);
                
    } catch (Exception ex) {
        ex.printStackTrace();
    }
}

Example C-3 Creating a Guest Virtual Machine From a Template Using Oracle JDeveloper

An Oracle JDeveloper proxy class for creating a guest virtual machine from a template might look similar to:

public static void main(String[] args) {
    try {
        LifecycleServiceSoapHttpPortClient myPort = 
           new LifecycleServiceSoapHttpPortClient();
        System.out.println("calling " + myPort.getEndpoint());
        // Add your own code here
        
        myPort.setUsername("myuser");
        myPort.setPassword("mypassword");

        TemplateVmConfig templateVMConfig= new  TemplateVmConfig();
        templateVMConfig.setServerPoolName("example.com");
            //your serverpoolName
        templateVMConfig.setTemplateName("myTemplate");//your templateName
    
        NICConfig nic = new NICConfig();
        nic.setName("VIF0");
        nic.setIpAddress("ioemu");
    
       nic.setBridge("xenbr0");
        nic.setMacAddress("00:16:xx:xx:xx:xx");
        NetworkConfType confType = new NetworkConfType();
        confType.setType("Dynamic");
        nic.setNetworkConfType(confType);
    
        //nic.set
        NICConfig[] vifs = new NICConfig[]{nic};
        templateVMConfig.setVif(vifs);

        templateVMConfig.setVmName("MyGuestVirtualMachine");
    
        templateVMConfig.setConsolePassword("mypassword");
        templateVMConfig.setHaEnable(false);

        myPort.createVmBasedOnTemplate(templateVMConfig);        
    } catch (Exception ex) {
        ex.printStackTrace();
    }
}

public LifecycleService _port;
public VirtualMachine createVmBasedOnTemplate(TemplateVmConfig templateVMConfig) throws java.rmi.RemoteException{
    ServiceFactory factory = ServiceFactory.newInstance();
    _port = ((LifecycleService_Service)factory.loadService(LifecycleService_Service.class))
            .getLifecycleServiceSoapHttpPort();    
   return _port.createVmBasedOnTemplate(templateVMConfig);
}

Using wsimport

To create a proxy class for an Oracle VM Manager Web service in Java using the wsimport utility:

$ JAVA_HOME/bin/wsimport -d <dir-for-compiled classes> -keep -s <dir-for-generated-source> -p com.oracle.ovm.manager.ws.vms -wsdllocation http://ovm_host:port/OVSWS/nameService.wsdl <path-to-wsdl-file-in-local-host>

For example, to create a proxy class for the ServerPool Web service, you might enter:

$ JAVA_HOME/bin/wsimport -d <dir-for-compiled classes> -keep -s <dir-for-generated-source> -p com.oracle.ovm.manager.ws.vms -wsdllocation http://example.com:8888/OVSWS/ServerPoolService.wsdl <path-to-wsdl-file-in-local-host>

Example C-4 Retrieving a Server Pool by Name Using wsimport

A wsimport proxy class for retrieving a server pool using its name might look similar to:

public ServerPool getServerPoolByName(String poolName) throws Exception{
        String url = "http://example.com:8888/";
        String contextPath = "OVSWS";
        String user = "myuser";
        String password = "mypassword";
        ServerPoolService_Service sps_service =
            new ServerPoolService_Service(new URL(url + contextPath +
               "/ServerPoolService.wsdl"),
            new QName("http://oracle.ovs.api/", "ServerPoolService"));
        sps = sps_service.getServerPoolServiceSoapHttpPort();
 
        BindingProvider bp = (BindingProvider) sps;
        Map<String, Object> rc = bp.getRequestContext();
        rc.put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, url + contextPath +
            "/ServerPoolServiceSoapHttpPort");
        rc.put(BindingProvider.SESSION_MAINTAIN_PROPERTY, new Boolean(true));
        rc.put(BindingProvider.USERNAME_PROPERTY, user);
        rc.put(BindingProvider.PASSWORD_PROPERTY, password);
 
        GetServerPoolByNameElement req = new GetServerPoolByNameElement();
        req.setPoolName(poolName);
        GetServerPoolByNameResponseElement res = sps.getServerPoolByName(req);
        ServerPool thePool = res.getResult();
        return thePool;
    }

Creating a Proxy Class in Python

To create a proxy (stub) class for an Oracle VM Manager Web service using Python:

$ wsdl2py -b http[s]://ovm_host:port/OVSWS/nameService.wsdl

For example, to create a proxy class for the ServerPool Web service, you might enter:

$ wsdl2py -b https://ovm.example.com:4443/OVSWS/ServerPoolService.wsdl

Example C-5 Retrieving a Server Pool by Name using Python

A Python proxy class for retrieving a server pool using its name might look similar to:

import ServerPoolService_client as c

class ServerPoolManagementPort:

    def __init__(self, urlbase, auth):
        self.wspath = "/ServerPoolServiceSoapHttpPort"
        self.loc = c.ServerPoolServiceLocator()
        self.srv = self.loc.getServerPoolServiceSoapHttpPort(url = urlbase +
            self.wspath, auth = auth)
    def getServerPoolByName(self, poolName):
        """
        Return instance os a specific server pool managed by the system, by its
            name.
        @param poolName:
        @type poolName: str
        @return: ServerPool
        """
        request = c.ServerPoolService_getServerPoolByName()
        request._poolName = poolName
        response = self.srv.getServerPoolByName(request)
        return response._result

To call this code, including authentication with the Web service, you might use:

from ServerPoolManagementPort import *
from ZSI.auth import AUTH
auth=(AUTH.httpbasic, 'myuser', 'mypassword')
spm = ServerPoolManagementPort(urlbase = 'https://ovm.example.com:4443/OVSWS/',
                   auth = auth)
serverpool = spm.getServerPoolByName('myserverpool')

Authentication and Security

The Oracle VM Manager Web services use HTTP basic authentication to authenticate users and control access. HTTP basic authentication requires that the server requests a username and password from the Web services client, and verifies that the username and password are valid by comparing them against a valid Oracle VM Manager user.

SSL is enabled by default for Web services, and secures the data during transmission at transport level. For each Web service call, the server authenticates the log in credentials for valid Oracle VM Manager users in the basic header.

If you need to set up SSL for Web services after the original Oracle VM Manager installation, you can use the script:

# /opt/ovs-manager-2.1/bin/secure_ws.sh

This script generates the keystore for Oracle VM Manager Web services and configures OC4J.

To perform the authentication with Oracle VM Manager, you must pass the Oracle VM Manager login credentials to the Oracle VM Manager Web service from a Web services client.

Example C-6 Authentication in Java

To perform HTTP basic authentication from a Java Web services client:

Change the URL to the Web service from http to https. For example, https://ovm.example.com:4443. This is the URL used to obtain the SOAP HTTP port in step 3.

Add the following two system properties to the client-side Java to perform the SSL handshake:

-Djavax.net.ssl.trustStore=/path/ovmm_client_trust.jks    <=== this contains the manager's cert
-Djavax.net.ssl.trustStorePassword=truststorepasswd

Obtain the SOAP HTTP port, with code similar to the following:

ServerPoolService_Service sps_service =
        new ServerPoolService_Service(new URL(url + contextPath +
               "/ServerPoolService.wsdl"),
        new QName("http://oracle.ovs.api/", "ServerPoolService"));
//Note, the URL here is the URL mentioned in Step 1. It is the HTTPS URL.
ServerPoolService sps = sps_service.getServerPoolServiceSoapHttpPort();

BindingProvider bp = (BindingProvider) sps;
Map<String, Object> rc = bp.getRequestContext();
rc.put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, url + contextPath +
     "/ServerPoolServiceSoapHttpPort");
rc.put(BindingProvider.SESSION_MAINTAIN_PROPERTY, new Boolean(true));
rc.put(BindingProvider.USERNAME_PROPERTY, myuser);
rc.put(BindingProvider.PASSWORD_PROPERTY, mypassword);

You must also generate a keystore and proxy on the Web services client. For example, you could use:

# java -Djavax.net.ssl.trustStore=/Users/myuser/ssl/client.keystore
-Djavax.net.ssl.keyStore=/Users/myuser/ssl/client.keystore
-Djavax.net.ssl.trustStorePassword=mypassword
-Djavax.net.ssl.keyStorePassword=mypassword
-jar $ORACLE_HOME/webservices/lib/wsa.jar
-genProxy
-wsdl https://ovm.example.com:4443/OVSWS/AdminServiceSoapHttpPort?WSDL

To set the login credentials on the Web services client, you could use:

System.setProperty("javax.net.ssl.trustStore", "/Users/myuser/ssl/client.keystore");
System.setProperty("javax.net.ssl.keyStore", "/Users/myuser/ssl/client.keystore");
System.setProperty("javax.net.ssl.trustStorePassword", "mypassword");
System.setProperty("javax.net.ssl.keyStorePassword", "mypassword");
...

Example C-7 Authentication in Python

An Python proxy class to authenticate and retrieve a server pool might look similar to:

import ServerPoolService_client as c
from ZSI.auth import AUTH
loc = c.ServerPoolServiceLocator()
auth = (AUTH.httpbasic, 'myuser', 'mypassword')
srv = loc.getServerPoolServiceSoapHttpPort(auth=auth)
req = c.ServerPoolService_getServerPoolByName()
req._poolName = 'myserverpool'
resp = srv.getServerPoolByName(req)
serverPool = resp._result

Web Service Locations

Each Oracle VM Manager Web service URL has the syntax:

http[s]://ovm_manager_host:port/OVSWS/WS_name.wsdl

SSL is enabled by default for Web services, and secures the data during transmission at transport level. Although you can access the Web services without using SSL, Oracle recommends you use SSL for increased security.

A test page is available for each Web service that enables you to test a Web service and values for the Web service parameters. The Web service test page URL has the syntax:

http[s]://ovm_manager_host:port/OVSWS/WS_nameSoapHttpPort

When you open a Web service test page in a browser, you must authenticate with the Web service by entering an Oracle VM Manager administrator username and password. When you have authenticated, a form is displayed that enables you to input parameters and invoke different methods in the Web service. This form also contains a link named Service Description that displays the WSDL for the Web service. The following is the syntax for the WSDL URL:

http[s]://ovm_manager_host:port/OVSWS/WS_nameSoapHttpPort?WSDL

http[s]://ovm_manager_host:port/OVSWS/WS_name.wsdl

The Web service test page also contains a link to the documentation for the Web service. The syntax for the Web service documentation is:

http[s]://ovm_manager_host:port/OVSWS/WS_nameSoapHttpPort?WS_ nameSoapHttpPortstub.html

For example, if your Oracle VM Manager host is ovm.example.com, and its port is 4443 and SSL is enabled, then the following URL is the location for the LifecycleService:

https://ovm.example.com:4443/OVSWS/LifecycleService.wsdl

And the location of the test page for LifecycleService is:

https://ovm.example.com:4443/OVSWS/LifecycleServiceSoapHttpPort

The corresponding LifecycleService documentation URL is:

https://ovm.example.com:4443/OVSWS/LifecycleServiceSoapHttpPort?LifecycleServiceSoapHttpPortstub.html

Web Services

The Oracle VM Manager Web services available are:

LifecycleService: Manages the lifecycle of virtual machines.
ResourceService: Manages resources.
PluginService: Manages the plug in.
ServerPoolService: Manages servers and server pools.
VirtualMachineService: Manages virtual machines.
AdminService: Manages users and groups.

LifecycleService

The LifecycleService Web service manages the lifecycle of virtual machines. You can use this Web service to create a virtual machine, enable HA, perform live migration, attach CDs and disks, and so on.

The LifecycleService Web service is located at:

http[s]://ovm_manager_host:port/OVSWS/LifecycleService.wsdl

The methods available in this Web service are:

addDisk
addNIC
attachCDtoVM
attachSharedVirtualDisk
changeNetworkType
clone
createVmBasedOnISO
createVmBasedOnPXE
createVmBasedOnTemplate
deploy
detachCD
detachSharedVirtualDisk
disableHA
enableHA
getConsolePassword
getKeyboardLayoutArray
getVMGroupByVMId
liveMigrate
liveMigrateAll
removeDisk
removeNIC
resetStatus
setBootPriority
setConsolePassword
setCPUCores
setDynamicMemory
setGuestCredential
setMaximumMemory
setNetworkInsideGuest
setOperatingSystem
setPreferredServers
setVMConfigParam
setVMDescription
setVMKeyboardLayout

More detailed information on the functions available in this web service is available in the Oracle VM Manager Web Services API Reference.

ResourceService

The ResourceService Web service manages resources. You can use this Web service to import and manage ISO files, templates, virtual machines, and shared virtual disks.

The ResourceService Web service is located at:

http[s]://ovm_manager_host:port/OVSWS/ResourceService.wsdl

The methods available in this Web service are:

ValidateVMConfig
approveISOResource
approveImage
approveTemplate
deleteISO
deleteImage
deleteSharedVirtualDisk
deleteTemplate
getAllDiscoverableISO
getAllDiscoverableImages
getAllDiscoverableTemplates
getAllISOResources
getAllImageResources
getAllSharedVirtualDisks
getAllTemplateResources
getISOResource
getISOResourceByGroupName
getISOResourceByGroupNameAndISOName
getISOResourceByISOName
getImageResource
getImageResourceByName
getSharedDiskResource
getSharedDiskResourceByName
getTemplateResource
getTemplateResourceByName
registerExternalISO
registerExternalImage
registerExternalTemplate
registerISO
registerInternalISO
registerInternalImage
registerInternalTemplate
registerSharedVirtualDisk

More detailed information on the functions available in this web service is available in the Oracle VM Manager Web Services API Reference.

PluginService

The PluginService Web service manages the plug in. You can use this Web service to set or get plug in scope properties.

The PluginService Web service is located at:

http[s]://ovm_manager_host:port/OVSWS/PluginService.wsdl

The methods available in this Web service are:

disposePlugin
getDaemonManager
preparePlugin

More detailed information on the functions available in this web service is available in the Oracle VM Manager Web Services API Reference.

ServerPoolService

The ServerPoolService Web service manages servers and server pools. You can use this Web service to create and manage servers and server pools.

The ServerPoolService Web service is located at:

http[s]://ovm_manager_host:port/OVSWS/ServerPoolService.wsdl

The methods available in this Web service are:

addMembers
checkHAAbility4ServerPoolById
checkServerConnection
checkVirtualServerCompatibility
createServerPool
deleteServerPool
getAgentVersion
getAllMembers
getAllServerPools
getClusterRootByServerPoolId
getMasterAgentStatus
getMasterServer
getMinSupportedOVSAgentVersion
getNetworkBridges
getNetworkBridgesByServerIP
getServer
getServerByName
getServerPool
getServerPoolById
getServerPoolByName
getServerPoolMetricsByServerPoolId
getServerPools
get StorageResositoriesByServerPoolId
getVirtualServerById
getVirtualServerByName
getVirtualServerByServerPool
getVirtualServerMetrics
getVirtualServers
rebootServer
refreshServerPool
removeMember
restoreVirtualServerPoolByManagerData
shutdownServer
updateServerPool
updateUserList4ServerPool
updateUtilityServerPassword
updateVirtualServer
updateVirtualServerAgentPassword
updateVirtualServerById
validateAddMembers
validateCreateServerPool
validateDeleteServerPool
valicateRebootServer
validateRemoveMember
validateShutdownServer
validateUpdateUtilityServerPassword
validateUpdateVSAgentPassword

More detailed information on the functions available in this web service is available in the Oracle VM Manager Web Services API Reference.

VirtualMachineService

The VirtualMachineService Web service manages virtual machines. You can use this Web service to create and manage virtual machines.

The VirtualMachineService Web service is located at:

http[s]://ovm_manager_host:port/OVSWS/VirtualMachineService.wsdl

The methods available in this Web service are:

createPropertiesFileOnVirtualMachine
deleteVMByVMId
getAllAlertAssociatedWithImg
getAllOperatingSystemArray
getAllVMs
getAssociatedPool
getAssociatedServer
getLastAlertAssociatedWithDisk
getLastAlertAssociatedWithImg
getRealPath
getVM
getVMByName
getVncPassword
pauseVMByVMId
powerOffVMByVMId
powerOnVMByVMId
queryCdromArray
queryLocalDiskInfo
queryLocalDisks
queryNetworkInterfaceCardArray
queryPreferredServer
querySharedDiskInfo
querySharedVirtualDiskArray
queryVMMetricArrayVyVMIds
queryVMMetricByVMId
queryVMStatusArrayByVMIds
queryVMStatusByVMId
rebootVMByVMId
resumeVMByVMId
saveAsTemplate
setVMName
suspendVMByVMId
unpauseVMByVMId
unregisterVMByVMId
update
uploadVirtualMachine

More detailed information on the functions available in this web service is available in the Oracle VM Manager Web Services API Reference.

AdminService

The AdminService Web service manages users and groups. You can use this Web service to create and manage users and groups.

The AdminService Web service is located at:

http[s]://ovm_manager_host:port/OVSWS/AdminService.wsdl

The methods available in this Web service are:

createGroup
createUser
createUserGroup
createUserSite
findAllOVMGroup
findAllOVMRole
finalAllOVMUser
findAllOVMUserGroup
findAllOVMUserRole
findAllOVMUserSite
findUserById
isAdminUser
login
logout
searchUsers

More detailed information on the functions available in this web service is available in the Oracle VM Manager Web Services API Reference.