+ Developer Guide Overview
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.
Contents
- 1 What's in the SDK
- 2 Supported Language / WebServices Compiler
- 3 Python Integration
- 4 PHP Integration
- 5 C++ SDK System Requirements
- 6 Compiling the sample .NET application
- 7 Async vs. Sync API calls
- 8 Task Monitoring
- 9 Event Polling & Registration
- 10 Custom Roles
- 11 Supported SOAP / WebServices Implementations
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)