SOAP

From Halon, SMTP software for hosting providers
Jump to: navigation, search

The Halon SMTP software can be fully controlled using SOAP (Simple Object Access Protocol) which is an XML-based RPC-over-HTTP protocol. The system's (built-in, jailed) web administration is in fact 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 (https://your-appliance-ip/remote/?wsdl). Modern browser may show a styled version of the WSDL file using XSL at https://your-appliance-ip/remote/.

It is highly recommended to create a custom SOAP user with the system authentication script, and restrict access only to its intended SOAP functions (with the required permissions to operate).

Authentication

Typically, HTTP basic authentication is used. However, If basic authentication is not supported in your SOAP client, the username and password may be passed using the query string:

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

Note: when passing username and password in the query string, be aware so that the username and password don't unintentionally end up in various log files/syslog (in proxies etc) before reaching the Halon.

Examples

Below are a few PHP examples. Begin by creating a SOAP client, that is used in all following examples.

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

Retrieve information about the three latest configuration revisions

$items $client->configRevisionLog(array('limit' => 3))->result->item;
var_dump($items); 

Search the message history

In this example the 50 latest messages to admin@example.org (according to the search filter syntax). The same parameters applies to mailQueue() for messages in quarantine and the outbound queue.

$items $client->mailHistory(array('filter' => 'to=admin@example.org''offset' => '0''limit' => 50))->result->item;
var_dump($items); 

Extract statistical information

$items $client->statList(array('key1' => 'hsl:stat''key2' => 'ip-family''key3' => 'ipv4'))->result->item;
var_dump($items); 

Get the current (running) configuration

var_dump($client->configKeys()->result->item); // returns an array 

Export the current (running) configuration

var_dump($client->configCheckout()->result); // returns the plain-text configuration 

Get a specific rate

$client->hslRate(['ns' => 'foo''entry' => 'bar']); // returns an array 

Add a domain with transport

$domain 'example.com';
$transport '1.1.1.1';

function 
configPackArray($array) {
        
$result = array();
        foreach (
$array as $k => $v)
                
$result[] = array('first' => $k'second' => $v);
        return 
$result;
}

$args = array(
        
'active'=>'yes',
        
'hostname'=>'internal-hostname',
        
'mailserver'=> $transport,
        
'port'=>'25',
        
'retrydelay'=>'15,30,60,240',
        
'retrycount'=>'30',
        
'tls'=>'optional',
        
'sourceip'=>'auto',
        
'dsn'=>'yes',
        
'comment'=>'',
        
'mode'=>'inbound',
        
'saslusername'=>'',
        
'saslpassword'=>'',
        
'protocol'=>'smtp',
        
'prioqueue'=>'no'
);   
$transport $client->configKeyAdd(array('key' => 'mail_transport''params' => configPackArray($args)));

$args = array(
        
'active'=>'yes',
        
'name'=>'',
        
'domain'=>$domain,
        
'server'=>'mailserver:1',
        
'transport'=>'mailtransport:'.$transport->result,
        
'dataflow'=>'dataflow:1',
        
'rcptflow'=>'rcptflow:1'
);
$client->configKeyAdd(array('key' => 'mail_domain''params' => configPackArray($args))); 

Executing a command, such as statd

$id $client->commandRun(array('argv'=> array('statd''-g''system-cpu-usage')));

try { 
        while(
true) {
                
$data $client->commandPoll(array('commandid' => $id->result));
                if (
$data->result->item)
                        echo 
implode(''$data->result->item);
        }
} catch(
SoapFault $f) {} 

Export mail history as CSV

Filter can be any Search filter.

$filter "from=user@example.org or to=user@example.com";
$items $client->mailHistory(array(
            
'filter' => $filter,
            
'offset' => '0',
            
'limit' => 10000))->result->item;
if (
is_array($items)) {
    
date_default_timezone_set('GMT0');
    
$out fopen('php://output''w');
    foreach (
$items as $item) {
        
fputcsv($out, array(
                    
date('Y-m-d H:i:s',$item->msgts),
                    
$item->msgaction,
                    
$item->msgfromserver,
                    
$item->msgfrom,
                    
$item->msgto,
                    
$item->msgsubject,    
                    ));
        
// var_dump($item);
    
}
    
fclose($out);

Export license usage per domain

$users $client->licenseUsers()->result->item;
$domains = [];
$longest 0;
if (
is_array($users)) foreach ($users as $user) {
    list(
$local$domain) = explode('@'$user);
    
$domains[$domain]++;
    
$longest strlen($domain) > $longest strlen($domain) : $longest;
}
arsort($domains);
foreach (
$domains as $d => $c)
    
printf("%-{$longest}$c\r\n"$d); 

Read from a file (tailing)

$read $client->fileRead(['file' => '/storage/log/mail.log''offset' => -1'size' => 0]);
while (
true)
{
    
$read $client->fileRead(['file' => '/storage/log/mail.log''offset' => $read->offset'size' => 8192]);
    if (
$read->size)
        echo 
$read->data;
    else
        
sleep(1);

Deleting specific items from the HSL cache

/*
$_POST['delete-item'] = true;
$_POST['ns']          = null;
$_POST['function']    = 'api_call_http';

$_POST['argument'][1] = 1;
$_POST['type'][1]     = 'string';
$_POST['value'][1]    = '&type=route&recipientdomain=$1';

$_POST['argument'][2] = 2;
$_POST['type'][2]     = 'json';
$_POST['value'][2]    = '["example.com"]';
*/

if (isset($_POST['delete-item']))
{
    
$item = [];
    if (
$_POST['ns'])
        
$item['ns'] = $_POST['ns'];
    if (
$_POST['function'])
        
$item['function'] = $_POST['function'];
    if (
$_POST['argument'])
        
$item['arguments'] = [];
    foreach (
$_POST['argument'] as $k => $i)
    {
        
$type $_POST['type'][$k];
        if (
$type == 'json')
            
$data $_POST['value'][$k];
        if (
$type == 'string')
            
$data json_encode($_POST['value'][$k]);
        
$item['arguments'][] = ['index' => $i'value' => $data];
    }
    
$client->hslCacheClear($item);

Updating contents of a HSL CSV file

function configPackArray($array) {
    
$result = array();
    foreach (
$array as $k => $v)
        
$result[] = array('first' => $k'second' => $v);
    return 
$result;
}            

$file 'file__domains';

$items = [];
$items[] = ['domain' => 'example.com''destination' => 'mail.example.com'];
$items[] = ['domain' => 'example.net''destination' => 'mail.example.net'];
$items[] = ['domain' => 'example.org''destination' => 'mail.example.org'];
$count count($items) - 1;

$data 'domain,destination'."\n";
foreach (
$items as $key => $value) {
    
$data .= $value['domain'].','.$value['destination'];
    if (
$key != $count$data .= "\n";
}

$args = array('data' => base64_encode($data));

$client->configKeySet(array('key' => $file'params' => configPackArray($args)));