SOAP

From securityrouter.org, an OpenBSD-based firewall
Jump to: navigation, search

The system may be fully controlled using our API. It's primarily SOAP[1] (Simple Object Access Protocol) which is an XML-based RPC-over-HTTP protocol. The web administration included is in fact a web site running inside a jail, connecting to the backend (control process) using SOAP. For local scripting see root access and configure.

REST proxy

REST[2] (Representational state transfer) or RESTful APIs have become increasingly popular. Because it's not perfectly fit for all the functionality that our system provides, our primary API is SOAP. We do however realise that there might be cases when SOAP is not an option, and therefore provide a REST proxy.

Documentation and usage

The API calls are listed and commented in the WSDL[3] (Web Service Definition Language) file, which is included on the appliance (https://your-appliance-ip/remote/?wsdl). Modern browser may show a styled version of the WSDL file using XLST at https://your-appliance-ip/remote/.

Normally, valid authentication should be passed using HTTP's "basic authentication" with each request. If it's unsupported in your SOAP client, the username and password may be passed using the query string like

https://your-appliance-ip/remote/?username=admin&password=secretpassword

Examples

An example in PHP how to checkout, modify and commit the configuration. This example is transaction safe, thus passing the checkout revision as argument to the commit function guaranteeing that no commit has been done in between. If the commit revision argument were -1 commit would always accept the new revision.

<?php
$client = new SoapClient('https://10.0.0.1/remote/?wsdl',array(
            'location' => 'https://10.0.0.1/remote/',
            'uri' => 'urn:halon',
            'login' => 'admin',
            'password' => 'secretpassword'
            ));

$cfgobj = $client->configCheckout();
$config = str_replace("8.8.8.8", "8.8.4.4", $cfgobj->config);

$revision = $client->configCommit(array(
            'revision' => $cfgobj->info->revision,
            'config' => $config,
            'message' => 'Changed DNS servers',
            'timeout' => 0
            ));
echo $revision->result."\n";
?>

An example in PHP how to run ping using SOAP. The argv parameter is executed as execvp(3), meaning that it's not executed in a shell, so there is no shell metacharacters available (like & ; " ' [...).

<?php
$commandid = $client->commandRun(array('argv'=>
            array('ping', '-c5', 'google.com')
            ));
$commandid = $commandid->result;

try {
    while(true) {
        $data = $client->commandPoll(array('commandid' => $commandid));
        if ($data->result->item) {
            echo implode('', $data->result->item);
        }   
    }
} catch(SoapFault $f) {
    echo "Process terminated... ($f->faultstring)\n";
}
?>

If using Python, this example uses the suds SOAP client.

from suds.client import Client
from suds.transport.http import HttpAuthenticated

t = HttpAuthenticated(username='admin', password='secretpassword')
client = Client('https://10.0.0.1/remote/?wsdl',
        location='https://10.0.0.1/remote/', transport=t, faults=False)
client.set_options(cache=None)
print client.service.getSerial()