SOAP
H/OS 2 appliances (such as the SPG and VSP) is controlled using SOAP (Simple Object Access Protocol) which is an XML-based RPC-over-HTTP protocol. The Web Administration included is in fact a AJAX (Web 2.0) application connecting to the backend (control process) using SOAP.
Thus, it is possible to build your own interfaces and systems using the WSDL (Web Service Definition Language) file included on the appliance (http://your-appliance-ip/halon.wsdl, accessible when logged in).
Contents |
PHP Examples
Below follows examples on how to connect to the interface using PHP. You may need to activate the [SoapClient] (php_soap.dll) extension in php.ini.
SOAP Example
<?php
try {
/*
* Configure SoapClient to connect to Halon SPG
*/
$client = new SoapClient('<local path to halon.wsdl>',array(
'location' => 'http://<host of halon>/remote/',
'uri' => 'urn:halon',
'login' => '<my username>',
'password' => '<my password>',
'connection_timeout' => 30,
'trace' => true
));
/*
* Fetch General Statitics
*/
$curtime = $client->__soapCall('System-GetKey',
array('parameters'=>
array('key'=>'system_time')
)
);
$uptime = $client->__soapCall('System-GetKey',
array('parameters'=>
array('key'=>'system_uptime')
)
);
$mail_i = $client->__soapCall('System-GetKey',
array('parameters'=>
array('key'=>'system_mail_total_in')
)
);
$mail_o = $client->__soapCall('System-GetKey',
array('parameters'=>
array('key'=>'system_mail_total_out')
)
);
$queue_i = $client->__soapCall('System-GetKey',
array('parameters'=>
array('key'=>'system_mail_queue_in')
)
);
$queue_o = $client->__soapCall('System-GetKey',
array('parameters'=>
array('key'=>'system_mail_queue_out')
)
);
echo "<b>General Information</b><br />";
echo "Current Time: ".$curtime->result->item."<br />";
echo "System Uptime: ".$uptime->result->item."<br />";
echo "<br /><b>Mail Statistics</b><br />";
echo "Mail Incoming Total: ".$mail_i->result->item."<br />";
echo "Mail Outgoing Total: ".$mail_o->result->item."<br />";
echo "Mail in Incoming Queue: ".$queue_i->result->item."<br />";
echo "Mail in Outgoing Queue: ".$queue_o->result->item."<br />";
} catch(SoapFault $f) {
var_dump($f);
}
?>
System Interface
Export Configuration
$configuration = $client->__soapCall('Config-RetrieveVersion',array('parameters'=>array('version'=>'-1')));
Mail Gateway Interface
Below follows examples of administrative tasks which may be useful to carry out using the SOAP interface.
Add a domain
This script requires a $client (object) see above.
$client->__soapCall('Mail-Domain-Add',
array('parameters'=>
array(
'active'=>'yes',
'name'=>'sample domain',
'domain'=>'example.org',
'incoming'=>'mailserver:1',
'outgoing'=>'mailtransport:1',
'flow'=>'mailflow:1',
'administrator'=>'admin@example.org',
'reports'=>'MTWHF 08:00',
'tpl'=>'',
'rcptflow'=>'disabled'
)
));
Delete a domain
This script requires a $client (object) see above.
$client->__soapCall('Mail-Domain-Del',
array('parameters'=>
array(
'id'=>'17'
)
));
Information/Statistics
Most of the information/statistics can be collected by using the System-GetKey function and by changing the key parameter for whatever information you want to collect. If some information is missing that you can see in the WebUI, or want to be able to see, please contact support@halonsecurity.com
// Collect Access Control Blocked Connections
$statistics = $client->__soapCall('System-GetKey',
array('parameters'=>
array('key'=>'system_mail_counter_ippolicy:blocked')
)
);
Access Control
Get the total amount of allowed/blocked connections by Access Control.
system_mail_counter_ippolicy:allowed system_mail_counter_ippolicy:blocked
System
Software
Version
Get the system version.
system_version
Configuration Export
$configuration = $client->__soapCall('Config-RetrieveVersion',array('parameters'=>array('version'=>'-1')));
Hardware
Model
Get Model.
system_model
CPU
Get CPU information.
system_cpu_speed system_cpu_count system_cpu_temperature system_cpu_usage
Memory
Get RAM information.
system_mem_total system_mem_usage
Storage
Get the size and % of used disk storage.
system_disk_size system_disk_usage
Time
Get the system uptime in seconds.
system_time
Uptime
Get the system uptime in seconds.
system_uptime
Mail Queues
Use System-GetKey function to collect total amount of mail in queues.
system_mail_queue_in system_mail_queue_out
Mail Flow
Use System-GetKey function to collect total amount of mail traffic in and out. If you want the information per-domain. append "_mailserver:X_domain" at the end, where mailserver:X is the incoming mailserver and domain is the domain. eg. "system_mail_counter_mail:incoming_mailserver:1_halon.se".
system_mail_total_in system_mail_total_out
Mail Scanning
Get mail scanning statistics (Deliver, DeliverAsSpam, Delete and Quarantine). If you want the information per-domain. append "_mailserver:X_domain" at the end, where mailserver:X is the incoming mailserver and domain is the domain. eg. "system_mail_counter_mail:mailscanner:deliver_mailserver:1_halon.se".
system_mail_counter_mail:mailscanner:deliver system_mail_counter_mail:mailscanner:deliver:spam system_mail_counter_mail:mailscanner:delete system_mail_counter_mail:mailscanner:quarantine
Graphs over time
If you inspect the url of a graph in the WebUI (right click, properties), it will include the key(s) it uses.
On Mail Gateway -> Reporting the Send/Received graph have a URL like this.
Extract the key parameter.
mail_day_mail:incoming|mail_day_mail:outgoing:deliver
It tells you that it graphs two values "mail_day_mail:incoming" and "mail_day_mail:outgoing:deliver". To get the same information by SOAP call this function.
$statistics1 = $client->__soapCall('System-GetGraphData',
array('parameters'=>
array('key'=>'mail_day_mail:incoming')
)
);
$statistics2 = $client->__soapCall('System-GetGraphData',
array('parameters'=>
array('key'=>'mail_day_mail:outgoing:deliver')
)
);
This can be applied on ALL graphs.
Python 2.6 (and older) Example
You will need the python-SOAPpy package, in Ubuntu and alike run "sudo apt-get install python-SOAPpy"
Extract all licensed users and sort by volume
from SOAPpy import SOAPProxy
import operator
server = SOAPProxy("http://address/remote/?USERNAME=admin&PASSWORD=admin")
# debug
#server.config.dumpSOAPOut = 1
#server.config.dumpSOAPIn = 1
domain = {}
for user in server._ns("urn:halon").__getattr__("Management-License-Users-Get")()[0] :
tmp = user.split('@', 2)
if len(tmp) != 2 : continue
if tmp[1] not in domain :
domain[tmp[1]] = 1
else :
domain[tmp[1]] += 1
for k, v in sorted(domain.items(), key=operator.itemgetter(1), reverse=True) :
print "%(domain)-35s | %(count)d" % { "domain" : k , "count" : v }
Python 2.7 Example
Since Python 2.7 the officially supported soap client is called suds. This client requires the halon.wsdl file to be located within the same directory as the script.
SOAP Example
This example was written, and kindly contributed, by Robert Nilsson, Kullander
import logging
import suds.client
import suds.transport.http
import getpass
import datetime
logging.basicConfig(level=logging.INFO)
#logging.getLogger("suds.client").setLevel(logging.DEBUG)
#logging.getLogger("suds.transport").setLevel(logging.DEBUG)
#logging.getLogger("suds.wsdl").setLevel(logging.DEBUG)
h = raw_input(" Host: ").strip()
u = raw_input(" User: ").strip()
t = suds.transport.http.HttpAuthenticated(username=u, password=getpass.getpass())
halon = suds.client.Client("file:halon.wsdl", port="halon", location="https://%s/remote/" % h, transport=t)
def systemGetKey(k, cls = lambda x: x):
v = getattr(halon.service, "System-GetKey")(k)
if v is not None:
if len(v[0]) == 1:
return cls(v[0][0])
else:
return map(cls, v[0])
else:
return None
def systemGetKeysLike(k, cls = lambda x: x):
v = getattr(halon.service, "Config-GetKeysLike")(k)
if v is not None:
if len(v[0]) == 1:
return cls(v[0][0])
else:
return map(cls, v[0])
else:
return None
print "----"
st = datetime.datetime.fromtimestamp(systemGetKey("system_time", int))
su = datetime.timedelta(seconds=systemGetKey("system_uptime", int))
print " system_model: %s" % systemGetKey("system_model")
print " system_version: %s" % systemGetKey("system_version")
print " system_time: %s" % st
print " system_uptime: %s" % su
print " system_start: %s" % (st - su)
print " system_mail_total_in: %i" % systemGetKey("system_mail_total_in", int)
print "system_mail_total_out: %i" % systemGetKey("system_mail_total_out", int)
print " system_mail_queue_in: %i" % systemGetKey("system_mail_queue_in", int)
print "system_mail_queue_out: %i" % systemGetKey("system_mail_queue_out", int)
print ""
domains = dict([(d["shortcut"], [d["params"][0][2], []]) for d in systemGetKeysLike("mail_domain_")])
domainAlias = systemGetKeysLike("mail_domainalias_")
if domainAlias is not None:
for a in domainAlias:
domains[a["params"][0][2]][1] += [a["params"][0][1]]
print "Domains:"
for k in sorted(domains.keys()):
print " * %s" % (domains[k][0]),
if len(domains[k][1]) > 0:
print "(%s)" % (", ".join(sorted(domains[k][1])))
else:
print ""
VB.NET Example
Prepare the halon.wsdl file for VB.NET implementation.
1. Download the halon.wsdl file from http://address/halon.wsdl
2. Open the halon.wsdl file in eg. WordPad, search for "halonHeader" and remove that <message></message> key.
Create a new project in VB.NET, right click on your project in the Solution Explorer and add a new Service Reference, browse to your halon.wsdl file. Declare the HalonClient.
Dim HalonClient As New ServiceReference1.halonPortTypeClient()
HalonClient.Endpoint.Address = New System.ServiceModel.EndpointAddress("http://address/remote/?USERNAME=admin&PASSWORD=admin")
Mail Gateway Interface
Add a domain
Try
HalonClient.MailDomainAdd("yes", "my domain", "example.org", "mailserver:1", "mailtransport:1", "mailflow:1", "", "", "", "")
Catch ex As Exception
MsgBox("Failed to add domain")
End Try
List all domains
Dim keylist() As ServiceReference1.configKey
keylist = HalonClient.ConfigGetKeysLike("mail_domain__")
For i = 0 To keylist.Length() - 1
MsgBox(keylist.ToArray(i).params.ToArray(2).ToString())
Next
Complete Example
Public Class Form1
Dim HalonClient As New ServiceReference1.halonPortTypeClient()
Private Sub Form1_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load
HalonClient.Endpoint.Address = New System.ServiceModel.EndpointAddress("http://192.168.1.1/remote/?USERNAME=admin&PASSWORD=admin")
Dim keylist() As ServiceReference1.configKey
keylist = HalonClient.ConfigGetKeysLike("mail_domain__")
For i = 0 To keylist.Length() - 1
MsgBox(keylist.ToArray(i).params.ToArray(2).ToString() + " (id=" + keylist.ToArray(i).shortcut + ")")
Next
keylist = HalonClient.ConfigGetKeysLike("mail_domainalias__")
For i = 0 To keylist.Length() - 1
MsgBox("alias " + keylist.ToArray(i).params.ToArray(1).ToString() + " (parent=" + keylist.ToArray(i).params.ToArray(2).ToString() + ")")
Next
End Sub
End Class
