DCImanager Documentation

Guide to ISPsystem software API

ISPSystem

This document describes how to call the panel functions through API.

Authentication methods


You must be logged in with the appropriate privileges to call a function.

Session unique ID authentication

You can use this method when working with the control panel through your web browser.
The following URL is called:

https://IP-address:1500/dcimgr?out=xml&func=auth&username=username&password=password

The control panel will return either an error message or the following XML document: 

<?xml version="1.0" encoding="UTF-8"?>
<doc ...>
<auth id="session number" level="user level">session number</auth>
...
</doc>

The session is bound to an IP address. You should pass the session id in the "auth" parameter with every call to the control panel:

https://IP-address:1500/dcimgr?auth=session_number&out=xml&func=function&parameter1=value&parameter2=value...

The session number is kept within 1 hour since the last call was made. If no calls are made during this period, you need to get authorized again. 
The access level defines the user permissions. 

authinfo authentication

This method can be used for a one-time remote function call. You can pass the "authinfo" parameter and specify a login and password of the user who performs the operation: call that functions, e.g.:

https://IP-address:1500/dcimgr?authinfo=admin1:mypasswd&out=xml&func=function&parameter1=value&parameter2=value...

You must send the "authinfo" parameter with every call to the control panel.

Key authentication

This method allows for though authentication of the user in the control panel from other systems. Only admin username and password are used. If the client is identified with an external script, for example, by the billing system, and he must be redirected to the control panel without sign in. To do so, the script must generate a secret key (a random line at least 16 symbols long). 

For example, s "1234567890qwertyuiop". 

The username is "John". The server administrator may use any of the above authentication methods and execute the following request:

https://URL/dcimgr?out=xml&authinfo=root:secret&func=session.newkey&username=vasya&key=1234567890qwertyuiop

The response is "ok" or an error message. 

If the response is "ok", the user will be redirected to the following URL:

https://URL/dcimgr?func=auth&username=vasya&key=1234567890qwertyuiop&checkcookie=no

Following the URL will authorize the user and delete the key.

You may specify the key from any IP address. After the user is granted access to the control panel, this IP address will be associated with the session. The key can be used only once. Access is allowed from any IP address (even from those that are denied to access the panel).

HTTP-requests


Supported methods: "GET" and "POST".

Calling functions with privileges of another user


To call a control panel function with privileges of another user, add the "su=user_name" parameter to the URL.  The server administrator can call functions with permissions of any user; resellers can do so with permissions of the users registered on their account. All other users cannot use this method.

Getting results in your native languages


To receive the function results or error messages in your native language, add the  "lang=language" parameter to the URL (e.g. lang=en). If you specify a non-existent language, a default language will be shown.

Function result output


The function output can be generated in XML, JSON, and text format. Add the "out=format_name" parameter.

The out parameter can have one of the following values:

  • xml —  XML will be sent to STDIN;
  • devel —  similar to XML, but the document contains the data that describes the user interface.
  • text — data structures in the text format will be generated
  • sjson — data structures in JSON.
  • json —  simple JSON pretty printer.
  • JSONdata —  similar to JSON, without interface description. 
  • xjson — similar to the default output (HTML) but in  JSON (we recommend that you use it for custom interface themes).
  • print —  HTML for printing. Can be used only for data lists

If the "out" parameter is missing, such data are considered to be used by the browser and are converted into HTML.

Local calls to the control panel


For local calls to the control panel you can use the internal utility "mgrctl" which has a number of benefits

  • calls are sent directly to the control panel;
  • there is no need to store a password, as the authentication is performed with permissions of the user who runs the script (if you need to perform operations as another user, use the "suparameter described above);
  • has built-in hints for all the functions and their parameters relevant to your server.

Example: getting a list of WWW-domains in ISPmanager


Following is an example of how to get a list of WWW domains. You can call all other functions in the same manner. 

The curl utility

curl -k -s "https://IP-address/ispmgr?authinfo=username:password&out=xml&func=webdomain"

The mgrctl utility

/usr/local/mgr5/sbin/mgrctl -m ispmgr webdomain

Perl

Install the LWP library. To work with XML documents, you will need the XML::LibXML library.


#!/usr/bin/perl -w
use CGI::Carp qw(fatalsToBrowser);
print "Content-type: text/html\n\n";

use LWP::UserAgent;
use XML::LibXML;

my $result;

# Create a pseudo-browser that will run as MSIE and send the request
$ua = LWP::UserAgent->new;
$ua->agent("Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.0)");
my $req = HTTP::Request->new(POST => 'https://IP-address /ispmgr');

$req->content("authinfo=username:password&out=xml&func=webdomain");

my $res = $ua->request($req);

# Check the result
if ($res->is_success) {
    $result = $res->content;
} else {
    die $res->status_line."\n";
}

# The $result variable contains either an XML document with the list of WWW domains,
# or the error message

my $parser = XML::LibXML->new();
my $doc = $parser->parse_string( $result );
my $root = $doc->documentElement();

# Get a list of WWW-domains
my @sites = ();
for( $root->findnodes( "elem/name" ) ){
    push @sites, $_->textContent;
}

# output the result to the screen
for( sort @sites ){
    print $_."<br>\n";
}

PHP

PHP allows using a URL like standard files. The DOM XML library handles XML documents:

<?php
   $result = "";
   $fh = fopen( "http://IP-ADDR/ispmgr?authinfo=username:password&out=xml&func=wwwdomain", "r" );
   while( $data = fread( $fh, 4096 ) ){
     $result .= $data;
   }
   fclose( $fh );

   // The $result variable contains either the XML document with the list of WWW domains,
   // or the error message

   $doc = new DOMDocument();
   if( $doc -> loadXML( $result ) ){
       $root = $doc->documentElement;
       foreach ( $root->childNodes as $elem ){
           foreach ($elem->childNodes as $node){
               if( $node->tagName == "name" ){
                   echo $node->nodeValue;
                   echo "\n";
               }
           }
       }
   }
?>

Python

Use the "urllib2" library to call a URL from Python.  Use the "xml.dom.minidom" library for working with XML documents. 

#!/usr/bin/env python
# -*- coding: utf-8 -*-

from urllib2 import urlopen
from xml.dom import minidom

print "Content-type: text/html\n\n"
res = urlopen('http://IP-ADDR/ispmgr?authinfo=username:password&func=wwwdomain&out=xml')

# The res variable contains either the XML document with the list of WWW domains,
# or the error message

xmldoc = minidom.parse(res)

# Get the list of WWW domains and display its result

for node in xmldoc.getElementsByTagName('elem'):
        for name in node.getElementsByTagName('name'):
                print ('%s<br>' % name.firstChild.nodeValue)

Request and result format


A request is described as follows:

Function: a function name to pass in the "func" parameter.

Parameters: a list of parameters and their brief description. If a function has no parameters, they are not specified. Parameters are passed in the format parameter=value.

Result: results may vary depending on the requested function:

  • list of elements (table);
  • list of  object parameters (form);
  • successful operation  (action);
  • error message. 

List of elements (table)

The XML document looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<doc>
    <elem>element parameters on the list</elem>
    <elem>element parameters on the list</elem>
    ...
    <elem>element parameters on the list</elem>
</doc>

Function result: only the element parameters are described. They are one or several XML-nodes with all possible attributes and values. For example: 

<?xml version="1.0" encoding="UTF-8"?>
<doc>
    <elem>
        <name>foo.org</name>
        <admin>foo_admin</admin>
        <php/>
        <ssi/>
        <user used="1" limit="10"/>
        <disk used="0" limit="10"/>
        <traf used="3542" limit="8192"/>
    </elem>
    <elem>
        <name>example.com</name>
        <admin>example</admin>
        <cgi/>
        <php/>
        <ssi/>
        <frp/>
        <user used="5" limit="50"/>
        <disk used="39" limit="50"/>
        <traf used="1084" limit="4096"/>
    </elem>
</doc>

List of object parameters (form)

The XML document looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<doc>
    <elid>object id</elid>
    object parameters
</doc>

Function result: object parameters are only described. These are one or several XML nodes with all possible attributes and values that describe properties of the object. 

Example:

<?xml version="1.0" encoding="UTF-8"?>
<doc>
    <elid>example.com</elid>
    <name>example.com</name>
    <gid>1001</gid>
    <alias>www.example.comtest.example.com</alias>
    <cgi/>
    <phptype>phpcgi</phptype>
    <ssi/>
    <frp/>
    <sslport>443</sslport>
    <alluser>50</alluser>
    <shelluser>5</shelluser>
    <domain>1</domain>
    <base>3</base>
    <traf>4096</traf>
    <disklimit>50</disklimit>
</doc>

Successful operation (action)

When creating, changing, removing, enabling or disabling an object, the XML document looks like this: 

<?xml version="1.0" encoding="UTF-8"?>
<doc>
    <ok/>
</doc>

Error message

If an error occurred while processing your request, the XML document looks like this: 

<?xml version="1.0" encoding="UTF-8"?>
<doc>
  <error type="exists" object="user" lang="ru">
    <param name="object" type="msg" msg="User">user</param>
    <param name="value">ben</param>
    <stack>
      <action level="30" user="jen">admin.edit</action>
    </stack>
    <group>__object__ with '__value__' already exists</group>
    <msg>User with 'ben' already exists</msg>
  </error>
</doc>

List of functions and parameters


The control panel parameters and function are described in DCImanager API.

The up-to-date information is also available on the master server. 

Get a full list of DCImanager functions:

/usr/local/mgr5/sbin/mgrctl -m dcimgr -i

Get the description of user list output (you can use the "lang" parameter to select a language) :

/usr/local/mgr5/sbin/mgrctl -m dcimgr -i user lang=ru

Generating an API-request from the log-file


The most convenient way to generate an API request is to perform a desired action in the panel interface and view the function and its parameters in the log file:

1. Open the log file of the control panel with the tail command:

tail -f /usr/local/mgr5/var/dcimgr.log | grep Request

2. Execute the action in the interface of the control panel. In the log file, you can see the function being executed at that moment and its parameters (it is shown in green color starting from INFO Request).

Creation of a domain name in ISPmanager log file looks like this:

Feb  6 08:08:07 [2346:23826] core_module INFO Request [188.120.252.33][root] 'clicked_button=ok&email_inaccess=&func=domain.edit&ip=8.8.8.8&ip_existing=&maildomain=off&name=domain.name&ns=ns1.example.com.%20ns2.example.com.&operafake=1486357687433&owner=www%2Droot&owner_admins=off&progressid=false&reversezone=&sfrom=ajax&sok=ok&web_inaccess=&webdomain=off&zoom-ip=&zoom-ns='

3. Generate an API request based on the function. The API request must have the format "https://<IP or domain name>:<the main port of the control panel>/<a short name of the control panel>?func=<function>&<parameter 1>=<value>&<parameter 2>=<value>...".

        Remove optional parameters from the request ("sfrom", "clicked_button", "operafake", "progressid", parameters equal to * and empty parameters), and create the  API request:

https://123.123.123.123:443/ispmgr?auth=a4b9816e498e&func=domain.edit&ip=8.8.8.8&maildomain=off&webdomain=off&name=domain.name&ns=ns1.example.com.%20ns2.example.com.&owner=www%2Droot&sok=ok&out=xml
Thank you for your feedback!
Was the article useful?
Tell us why not:

it does not match the title

it was hard to understand

I didn't find the answer

recommendations from the article did not help

other

Tell us what you didn't like in the article: