This is documentation for an outdated product. See the current documentation

ISPmanager 5 Business Documentation

/
/
/
Guide to ISPmanager software API

Guide to ISPmanager software API

 

This document covers the control panels' APIs. You need to be logged in with the appropriate privileges to call a function.

Authentication methods

Session unique ID authentication

You can use this method when working with a control panel through your web browser.

Follow the link

[https://IP-address:1500/ispmgr?out=xml&func=auth&username=user_name&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 id"/>
</doc>

You should specify this session id in the auth parameter to each call to a control panel. The session id is valid during one hour. If you do not send any requests to the control panel during that period, you will have to get authorized again.

[https://IP-address:1500/ispmgr?auth=session_id&out=xml&func=function&parameter1=value&parameter2=value|https://IP-address:1500/ispmgr?auth=session_id&out=xml&func=function&parameter1=value&parameter2=value] ...

In the URL above you may use the following internal control panel's names:

  • ispmgr — ISPmanager
  • core -COREmanager

authinfo authentication

This method can be used for remote function calls. To call ab ISPmanager function, you need to add the authinfo parameter and specify a login and password of the user who will call that functions:

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

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

Key authentication

This method allows using the administrator's login or password.

The key is a random line at least 16 symbols long, such as 1234567890qwertyuiop

The username is "John".

A server administrator may use any of the above authentication methods and execute the following request:

https://URL:1500/ispmgr?out=xml&func=session.newkey&username=vasya&key=1234567890qwertyuiop

In case of errors an error message will return. If not, the user will be redirected to

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

Following the above link 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).

Calling ISPmanager function with privileges of another user

To call an ISPmanager function with privileges of another user, add su=user_name to the URL. A server administrator can call functions as any user; resellers can do so with privileges of their user accounts. All other users cannot use this method.

Getting results in native languages

To get function results or error messages in your native language, add the lang=language to request (e.g. lang=en). If you specify a non-existent language, a default language will be used (normally, it is English, en)

Output of function results

Output can be generated in XML, JSON and text format. If you wish to receive output results in a specific format, specify the out=format_name parameter.

The out parameter can have one of the following values:

  • xml — data structures in XML will be generated.
  • devel — similar to XML, but the document will contain data describing the user's interface.
  • text — data structures in the text format will be generated
  • json — data structures in JSON will be generated. More information can be found here .
  • JSONdata — similar to JSON. Only data are described
  • print — html for printing. Can be used only for data lists
  • xxxx — you can create a custom output format, if needed. For more read in Creating of own output format.

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

Local calls to control panel

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

  • calls are sent directly to the control panel (they do not depend on the web-server)
  • there is no need to store a password, as authentication is always made with permissions of the user who run the script (if you need to perform operations as another user, use the su parameter described above).
  • has a built-in hints to all functions and their parameters relevant to your server

Getting a list of WWW-domains in ISPmanager

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

The curl utility

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

The mgrctl utility

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

Perl

If you are using 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|http://perldoc.perl.org/functions/qw.html] (fatalsToBrowser);
[print|http://perldoc.perl.org/functions/print.html]  "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:1500/ispmgr');

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

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

# Check results
if ($res->is_success) {
	$result = $res->content;
} else {
	[die|http://perldoc.perl.org/functions/die.html]  $res->status_line."\n";
}

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

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

# Get the list of WWW domains
my @sites = ();
for( $root->findnodes( "elem/name" ) ){
	[push|http://perldoc.perl.org/functions/push.html]  @sites, $_->textContent;
}

# Display the result
for( [sort|http://perldoc.perl.org/functions/sort.html]  @sites ){
	[print|http://perldoc.perl.org/functions/print.html]  $_."<br>\n";
}

PHP

PHP enables to use URL like standard files. The DOM XML library is used to handle XML documents:

<?php
   $result = "";
   $fh = [fopen|http://www.php.net/fopen] ( "http://127.0.0.1:1500/ispmgr?out=xml&func=webdomain", "r" );
   while( $data = [fread|http://www.php.net/fread] ( $fh, 4096 ) ){
     $result .= $data;
   }
   [fclose|http://www.php.net/fclose] ( $fh );

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

if( $doc = [domxml_open_mem|http://www.php.net/domxml_open_mem] ( $result ) ){
      $root = $doc->document_element();
      for( $elem = $root->first_child(); $elem; $elem = $elem->next_sibling() ){
         for( $node = $elem->first_child(); $node; $node = $node->next_sibling() ){
            if( $node->node_name() == "name" ){
               echo $node->get_content();
               echo "\n";
            }
         }
      }
   }
?>

Python

You should use the urllib2 library. 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://127.0.0.1:1500/ispmgr?func=webdomain&out=xml')

# The res variable contains either the XML document with the list of WWW domains, 
# or an 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)

Format of requests and results

Requests are described as follows:

Function: a function name to be passed 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)

The XML document will look 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>

Result: only the element parameters are described. They are one or several XML-nodes containing 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 will look like this:

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

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

<?xml version="1.0" encoding="UTF-8"?>
<doc>
	<elid>example.com</elid>
	<name>example.com</name>
	<gid>1001</gid>
	<alias>www.example.com test.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 will look like this:

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

If the web-server needs to be rebooted

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

To reboot the web-server click the link below:

[http://IP-address:1500/ispmgr?out=xml&func=restart|http://IP-address:1500/ispmgr?out=xml&func=restart]

Error message

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

<?xml version="1.0" encoding="UTF-8"?>
<doc>
	<error>error message.</error>
</doc>

For more information, please refer to Error codes .

List of functions and parameters

Parameters and Function of every control panel are described in separate articles of our Documentation (the articles are generated automatically). They contains all of the functions and parameters, which, however, may be not available in your installation.

Use the mgrctl -i utility to get up-to-date information

To get a full list of ISPmanager functions, you may execute the command

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

To get data description (the lang parameter can be used to get information in a required language)

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

How to generate an API request using the log file

The easiest 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.

Complete the following steps:

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

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

where XXX is a short name of the control panel. For example: bill, isp, vm, dci

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

For example, creating 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='

Let's generate the API request based on the function.

An API request must have the format https://:/?func=&=&=...

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|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]

 

In this article