Chapter 4 Additional Utilities Exposed in the WS-API

Authentication for the REST interface to the Web Services Utilities API follows the same approach as that used to authenticate against the Oracle VM Manager REST API, see Section 3.2, “How do I Authenticate?” for more information. If your client is already authenticated, there should be no reason to perform authentication again in order to access the Utilities API.

The Utilities API can be accessed by appending "/Utilities" to the URI. Therefore, the base URI to access the utilities via the REST interface is:

https://hostname:port/ovm/core/wsapi/rest/Utilities

In this URI, replace hostname with the host name or IP address of Oracle VM Manager, and replace port with the number of the port where the REST web service is available - the default is 7002 (SSL).

In terms of the REST interface to the Web Services Utilities API, different methods exposed by the API are grouped together based on their functional relationships to Oracle VM Manager to create separate utilities. Each utility has its own relative path beyond the base URI that provides access to the methods that are available for that utility. The relative paths and a description of the utility is provided below:

The methods available for each of the utilities is documented fully in the documentation provided with the SDK. The reader is encouraged to refer to this documentation to discover the full range of functionality provided by the Web Services Utilities API.

The Java example source code provided in OvmWsUtilitiesRestClient.java, in the SDK, provides excellent examples of how to access the methods exposed through the REST API using the Jersey Bundle tools. In the highly truncated sample below, it is easy to see that the different utility paths defined above are set as string values that can be combined to construct the correct URI to access each utility:

...
public class OvmWsUtilitiesRestClient extends RestClient implements OvmWsUtilitiesClient
{
    private static final String ATTRIBUTES_PATH            = "attributes";

    private static final String UTILITIES_PATH             = "Utilities";
    private static final String BUSINESS_MANAGEMENT_PATH   = "BusinessManagement";
    private static final String STATISTICS_MANAGEMENT_PATH = "StatisticsManagement";
    private static final String STATISTICS_ATTRIBUTES_PATH = ATTRIBUTES_PATH;
    private static final String MAC_MANAGEMENT_PATH        = "MacManagement";
    private static final String MAC_ATTRIBUTES_PATH        = ATTRIBUTES_PATH;
    private static final String ARCHIVE_MANAGEMENT_PATH    = "ArchiveManagement";
    private static final String ARCHIVE_ATTRIBUTES_PATH    = ATTRIBUTES_PATH;
    private static final String BACKUP_MANAGEMENT_PATH     = "BackupManagement";
    private static final String BACKUP_ATTRIBUTES_PATH     = ATTRIBUTES_PATH;
    private static final String EVENT_MANAGEMENT_PATH      = "EventManagement";
    private static final String EVENT_ATTRIBUTES_PATH      = ATTRIBUTES_PATH;
    private static final String SVR_EVENT_ATTRIBUTES_PATH  = "serverAttributes";
    private static final String JOB_MANAGEMENT_PATH        = "JobManagement";
    private static final String JOB_ATTRIBUTES_PATH        = ATTRIBUTES_PATH;
    private static final String LOG_MANAGEMENT_PATH        = "LogManagement";
    private static final String LOG_LOGGERATTRIBUTES_PATH  = ATTRIBUTES_PATH;
    private static final String RAS_MANAGEMENT_PATH        = "RasManagement";
    private static final String MODEL_MANAGEMENT_PATH      = "ModelManagement";
    private static final String USER_PREFERENCE_PATH       = "UserPreference";

    private final URI           businessManagementURI;
    private final URI           backupManagementURI;
    private final URI           logManagementURI;
    private final URI           jobManagementURI;
    private final URI           modelManagementURI;

    public OvmWsUtilitiesRestClient(final RestClient parentClient)
    {
        super(parentClient, UTILITIES_PATH);

        businessManagementURI = UriBuilder.fromUri(getBaseURI()).segment(BUSINESS_MANAGEMENT_PATH).build();
        backupManagementURI = UriBuilder.fromUri(getBaseURI()).segment(BACKUP_MANAGEMENT_PATH).build();
        logManagementURI = UriBuilder.fromUri(getBaseURI()).segment(LOG_MANAGEMENT_PATH).build();

        jobManagementURI = UriBuilder.fromUri(getBaseURI()).segment(JOB_MANAGEMENT_PATH).build();
        modelManagementURI = UriBuilder.fromUri(getBaseURI()).segment(MODEL_MANAGEMENT_PATH).build();
    }

    @Override
    public BusinessSelection<EthernetPort> utilGetAvailableEthernetPorts(final Id<Server> serverId, 
               final Id<Network> networkId)
        throws WsException
    {
        try
        {
            final Map<String, Object> queryParameters = createQueryParameterMap("serverId", serverId.getValue());
            if (networkId != null)
            {
                queryParameters.put("networkId", networkId.getValue());
            }
            final Builder b =
                    getResourceFromUriAndPathElementsWithQueryParameters(businessManagementURI, queryParameters,
                                                                         "availableEthernetPorts");

            @SuppressWarnings("unchecked")
            final BusinessSelection<EthernetPort> ethernetPorts = b.get(BusinessSelection.class);

            return ethernetPorts;
        }
        catch (final UniformInterfaceException ex)
        {
            throw convertException(ex);
        }
    }

...
}

In the code above, also included, is an example definition for the utilGetAvailableEthernetPorts method. Here you can see that since this class extends the RestClient class, it is able to use the getResourceFromUriAndPathElementsWithQueryParameters method in conjunction with the Jersey Builder to submit an HTTP GET request that returns the available Ethernet ports.

According to the documentation provided with the SDK, and extrapolating from the Java code, it should be easy to replicate this example in Python. The sample presented below provides a complete example of the Python code required to construct a similar query:

# import the requests library to handle HTTP requests and session maintenance
import requests
# import the json library for JSON translation (not required for this example)
import json

# instantiate a session object and populate it with authentication credentials
s=requests.Session()
s.auth=('user','password')
s.verify=False #disables SSL certificate verification
# configure the session to always use JSON
s.headers.update({'Accept': 'application/json', 'Content-Type': 'application/json'})

# set up a baseUri object to contain the URI to the Utilities API
baseUri='https://127.0.0.1:7002/ovm/core/wsapi/rest/Utilities'

# construct the URI according to the requirements set out in the documentation
uri='{base}/BusinessManagement/availableEthernetPorts'.format(
    base=baseUri)

# configure the query parameters
params={
    "serverId": "00:e0:81:4d:40:f5:00:e0:81:4d:40:be:00:e0:81:4d",
    "networkId": "0aac4c00"
}

# submit a get request to the uri and store the response
r=s.get(uri,params=params)
# use the requests library's native json parser to obtain a usable python object
availPorts=r.json()

The Utilities API significantly includes a set of methods that allow you to manage certificate generation and registration within Oracle VM Manager. This is important as the WS-API also allows for certificate-based authentication, allowing you to further secure how custom-developed applications authenticate and interact with Oracle VM Manager. This section explores some of these methods briefly in the context of the REST API.

Certificate management within Oracle VM Manager is discussed in a variety of contexts throughout the documentation. For more information on authenticating using an SSL certificate using REST, please see Section 3.6.2, “Authenticating”. Please also refer to Setting Up SSL in the Oracle VM Administrator's Guide for more information on SSL certificate management.

https://hostname:port/ovm/core/wsapi/rest/Utilities/Certificate/CaCertificate

https://hostname:port/ovm/core/wsapi/rest/Utilities/Certificate

https://hostname:port/ovm/core/wsapi/rest/Utilities/Certificate?sign=True

$ keytool -genkey

$ keytool -export -rfc

LoginCertificate cert = new LoginCertificate();
cert.setCertificate("-----BEGIN CERTIFICATE-----" +
    "MIIDTzCCAw2gAwIBAgIEIIUUWjALBgcqhkjOOAQDBQAweTELMAkGA1UEBhMCVVMxCzAJBgNVBAgT" +
    "AkNBMRUwEwYDVQQHEwxSZWR3b29kIENpdHkxDzANBgNVBAoTBk9yYWNsZTEaMBgGA1UECxMRT3Jh" +
    "Y2xlIFZNIE1hbmFnZXIxGTAXBgNVBAMTEENlcnRpZmljYXRlIERlbW8wHhcNMTMwODIxMTYzOTUz" +
    "WhcNMTMxMTE5MTYzOTUzWjB5MQswCQYDVQQGEwJVUzELMAkGA1UECBMCQ0ExFTATBgNVBAcTDFJl" +
    "ZHdvb2QgQ2l0eTEPMA0GA1UEChMGT3JhY2xlMRowGAYDVQQLExFPcmFjbGUgVk0gTWFuYWdlcjEZ" +
    "MBcGA1UEAxMQQ2VydGlmaWNhdGUgRGVtbzCCAbgwggEsBgcqhkjOOAQBMIIBHwKBgQD9f1OBHXUS" +
    "KVLfSpwu7OTn9hG3UjzvRADDHj+AtlEmaUVdQCJR+1k9jVj6v8X1ujD2y5tVbNeBO4AdNG/yZmC3" +
    "a5lQpaSfn+gEexAiwk+7qdf+t8Yb+DtX58aophUPBPuD9tPFHsMCNVQTWhaRMvZ1864rYdcq7/Ii" +
    "Axmd0UgBxwIVAJdgUI8VIwvMspK5gqLrhAvwWBz1AoGBAPfhoIXWmz3ey7yrXDa4V7l5lK+7+jrq" +
    "gvlXTAs9B4JnUVlXjrrUWU/mcQcQgYC0SRZxI+hMKBYTt88JMozIpuE8FnqLVHyNKOCjrh4rs6Z1" +
    "k$ keytool -import -file newcertW6jfwv6ITVi8ftiegEkO8yk8b6oUZCJqIPf4VrlnwaSi" +
    "6bc9ozDyK1cgNyZWl4kq1efzjsyolIr1i4CiM/MqnEZO43hVVtXex3V+VWd9i/CLn0I/ZC9Lfi5X" +
    "HlQOEzWKK/esvf64Mv96DbZna/XRj6JhTEPGoStizNhXrVJCF4DaiIP+l53qYKJEtrNoR+tToRt8" +
    "OimE3PzLCXILvwwaCaMhMB8wHQYDVR0OBBYEFAtyjCpfkznpsUf2Lj8iBmRS3/0oMAsGByqGSM44" +
    "BAMFAAMvADAsAhRTm5NW8HDcM8jG5a7QIowNLN+fEQIUZXMogTvKbcXu6NN6fh0KY09hokI=" +
    "-----END CERTIFICATE-----");

LoginCertificate signed = ovmUtil.certificateSignAndRegister(cert);
System.out.println(signed.getCertificate());

$ keytool -import -file newcert

$ openssl genrsa -des3 -out mykey.pem 2048
$ openssl req -new -key mykey.pem -out mycertreq.csr
$ openssl x509 -req -days 365 -in mycertreq.csr -signkey mykey.pem -out mycert.pem

cert=open('/path/to/mycert.pem').read()
body={'certificate': cert}
r=s.post('https://127.0.0.1:7002/ovm/core/wsapi/rest/Utilities/Certificate?sign=True',
          data=json.dumps(body))
signed_cert=r.json()['certificate']
f=open('/path/to/signed.pem','w')
f.write(signed_cert)
f.close()

$ cat /path/to/signed.pem /path/to/mykey.pem >> /path/to/OVMSignedCertificate.pem