Difference between revisions of "+ Developer Guide Overview"

Revision as of 15:13, 23 July 2012

QuantaStor was designed from the ground up so that you can develop your own applications to remotely manage your storage systems. That said, if all you need is a simple script to do some provisioning then you should be able to do everything you need just with the QuantaStor Remote Management CLI. The CLI is completely scriptable and has an xml output mode (--xml) so the output is easy to parse with any scripting language. For more advanced integrations we recommend using the QuantaStor WebServices interface directly. This interface allows you to communicate with the storage system using .NET on Windows and via various SOAP implementations on all platforms.

The QuantaStor Manager web interface and QuantaStor Remote Management CLI both manage the QuantaStor storage system via the QuantaStor WebServices / SOAP interface. A copy of the WebServices interface for QuantaStor is included with the SDK and is also included with every QuantaStor system and can be accessed via your web browser by simply entering this URL:

https://<QuantaStor-system-IP-address>:5151/osn.wsdl

For example, if your QuantaStor storage system has an IP address of 192.168.0.88, then you can access the WSDL [Services Definition Language)] file using this URL:

https://192.168.0.88:5151/osn.wsdl

In case you don't have a system handy, you can browse this copy but note you'll want to use the most recent version included with the [SDK] which is available from the downloads page.

What's in the SDK

The SDK includes a sample C# application that allows you to list and provision volumes in a storage system, some getting started documentation, the QuantaStor API/WSDL file, and a storage system simulator.

The QuantaStor Storage System Simulator runs on any Windows box and is installed automatically when you install the SDK package. You can run it from the Start menu in windows or you can run it on the command line with these arguments qs_service.exe --debug and it's up and running. From there you can manage the simulated storage system using the qs CLI or via your custom WebServices client application.

Supported Language / WebServices Compiler

• C++ (all platforms) / gSOAP 2.7.x
• PHP
• Python
• Java (all platforms) / Apache Axis 1.4
• Microsoft C# (Windows) / Microsoft VS WSDL Compiler
• Microsoft VB (Windows) / Microsoft VS WSDL Compiler

There are other languages such as Python, Perl, PHP, and others that all have WebServices/SOAP implementations and should work fine with QuantaStor but we have as of yet not tested these out. (Note: QuantaStor storage systems utilize gSOAP and Axis internally)

Python Integration

We've found SUDS to be the easiest Python based API to use to integrate with QuantaStor via SOAP. Here's a quick script which you can implement from within your QuantaStor system to communicate with the locally running core QuantaStor SOAP service:

#!/usr/bin/python
from suds.client import Client

wsdlUrl = 'file:///opt/osnexus/quantastor/lib/osn.wsdl'
client = Client(wsdlUrl)
client.set_options(soapheaders=("admin","password"), location='http://localhost:5152')
print client

result = client.service.echo("hello ray")
print result

Before the above noted script will work you'll first need to install SUDS like so:

sudo -i
wget https://fedorahosted.org/releases/s/u/suds/python-suds-0.4.tar.gz
tar xvfz python-suds-0.4.tar.gz
cd python-suds-0.4/
chmod 755 setup.py
./setup.py build
./setup.py install

For a secure connection to QuantaStor over SSL use the following:

#!/usr/bin/python
from suds.client import Client


import urllib2 as u2
from suds.client import Client
from suds.transport.http import HttpTransport, Reply, TransportError
import httplib

class HTTPSClientAuthHandler(u2.HTTPSHandler):
    def __init__(self, key, cert):
        u2.HTTPSHandler.__init__(self)
        self.key = key
        self.cert = cert

    def https_open(self, req):
        #Rather than pass in a reference to a connection class, we pass in
        # a reference to a function which, for all intents and purposes,
        # will behave as a constructor
        return self.do_open(self.getConnection, req)

    def getConnection(self, host, timeout=300):
        return httplib.HTTPSConnection(host, key_file=self.key, cert_file=self.cert)

class HTTPSClientCertTransport(HttpTransport):
    def __init__(self, key, cert, *args, **kwargs):
        HttpTransport.__init__(self, *args, **kwargs)
        self.key = key
        self.cert = cert

    def u2open(self, u2request):
        """
        Open a connection.
        @param u2request: A urllib2 request.
        @type u2request: urllib2.Requet.
        @return: The opened file-like urllib2 object.
        @rtype: fp
        """
        tm = self.options.timeout
        url = u2.build_opener(HTTPSClientAuthHandler(self.key, self.cert))
        if self.u2ver() < 2.6:
            socket.setdefaulttimeout(tm)
            return url.open(u2request)
        else:
            return url.open(u2request, timeout=tm)
import logging
logging.basicConfig(level=logging.INFO)
logging.getLogger('suds.client').setLevel(logging.DEBUG)
logging.getLogger('suds.transport').setLevel(logging.DEBUG)

transport = HTTPSClientCertTransport("/opt/osnexus/common/lib/qsclient.pem", "/opt/osnexus/common/lib/qscacert.pem")
url = 'https://192.168.0.142:5151/osn.wsdl'
client = Client(url, transport=transport)


#client = Client(url)
#print client
userid="admin"
passwd="password"
client.set_options(soapheaders=(userid,passwd), location='http://localhost:5152')
result = client.service.echo("hello ray")
print result

PHP Integration

You can integrate QuantaStor with your web services via PHP using our SOAP/WebServices interface as well. First you'll want to download and install the PHP wsdl compiler wsdl2php. Here's the series of commands to run to install this on an Ubuntu machine, this will vary a bit depending on your linux distro and you'll want to check the wsdl2php web site on sourceforge for the latest version of the compiler.

sudo -i
apt-get update
apt-get install php5-cli php-pear
wget http://superb-sea2.dl.sourceforge.net/project/wsdl2php/wsdl2php/wsdl2php-0.2.1-pear/wsdl2php-0.2.1-pear.tgz
pear install wsdl2php-0.2.1-pear.tgz
wget http://www.osnexus.com/storage/sdk/osn.wsdl
wsdl2php osn.wsdl

Now that you have wsdl2php installed you can compile the osn.wsdl file that is distributed with QuantaStor. Then end result will be a file called Service.php which you can find an example of here: Service.php This links to a PHP service file built using the QuantaStor v1.5 WSDL which can be found here: osn.wsdl

Here's a sample script that gets the storage system object information for the QuantaStor system you're connecting to:

[NOTE: This sample is a work in progress.. not yet ready.]

#!/usr/bin/php
<?php
require_once 'Service.php';
echo '<title>My First QuantaStor PHP Script</title>';
$qs_service = new Service();
$parameters = new storageSystemGet();
print $qs_service->storageSystemGet($parameters);
?>

C++ SDK System Requirements

You need a Windows system to install the SDK but once you have the included WSDL file you can copy that to any system to do your development from. The simulator only uses about 20M of RAM so you can run it on pretty much anything so the SDK system requirements are very minimal.

Compiling the sample .NET application

Async vs. Sync API calls

Task Monitoring

Event Polling & Registration

Custom Roles

Supported SOAP / WebServices Implementations

• gSOAP (C++, all platforms)
• Apache Axis (Java, all platforms)
• .NET (C# & Visual Basic, Windows)