Working with API

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/manager/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/manager/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
  • billmgr - BILLmanager
  • vdsmgr - VDSmanager
  • dsmgr - DSmanager
  • dnsmgr - DNSmanager
  • ipmgr - IPmanager

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/manager/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.

Trusted IP-addresses authentication

This method can be used for remote calls from a specific IP-address. For example, a billing system is installed on the server and requests the information about traffic or dick space consumption, number of WWW domains, and so on at regular intervals. This method allows to specify the line below in the configuration file, rather than complete the authentication procedure.

TrustIP IP-address user

where "IP-address" is an IP address of the server from which requests to the control panel are sent, "User" (optional parameter) is a user name who accesses the control panel. If it is not specified, requests will be sent with root privileges.

ISPmanager local function calls

This method can be used for local calls from external programs and scripts. For example, a call to the control panel from a custom script that is executed via cron at regular intervals. The control panel traces the UID of the process that makes the request and processes it with privileges of the user who has this UID. No other authentication data are required.

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/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/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).

HTTP or HTTPS?

To transfer passwords and session IDs through HTTP is considered potentially insecure. That's why the control panel checks that IP-address of the host that makes a request matches the IP address of the server where it is installed. If yes, i.e. in case of local call of ISPmanager functions, HTTP is allowed. Otherwise, only HTTPs can be used. When calling the control panel through HTTP, the error message will be returned.

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 with privileges of any user; resellers can do so with privileges of their user accounts. All other users cannot use this method.

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 fetch command

fetch -q -o - "http://IP-address/manager/ispmgr?out=xml&func=wwwdomain"

The curl command

curl -k -s "http://IP-адрес/manager/ispmgr?out=xml&func=wwwdomain"

perl

If you are using Perl, install the LWP library. For working with XML documents you 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/manager/ispmgr');
 
$req->content("authinfo=логин:пароль&out=xml&func=wwwdomain");
 
my $res = $ua->request($req);
 
# Проверим результат
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 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 @sites, $_->textContent;
}
 
# Display the result
for( sort @sites ){
	print $_."<br>\n";
}


PHP

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

<?php
   $result = "";
   $fh = fopen( "http://127.0.0.1/manager/ispmgr?out=xml&func=wwwdomain", "r" );
   while( $data = fread( $fh, 4096 ) ){
     $result .= $data;
   }
   fclose( $fh );
 
   // The $result variable contains either an XML document with the list of WWW domains,
   // or an error message
 
   if( $doc = 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/manager/ispmgr?func=wwwdomain&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)

The mgrctl utility

Alternatively, you can use the internal utility mgrctl that directly calls a control panel (it does not depend on the web-server). This is a more preferable method for local calls to functions of your product through API.

Output of the 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.

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

XML output format

To receive XML data, add the out=xml parameter to the control panel's query. The result will vary depending on a function you want to call. Thus, if you receive a list of elements, the function returns the XML document containing a list of XML nodes, one per element. Each node, in its turn, consists of a set of nodes determining parameters of this element. For example, when requesting a list of WWW domains from the control panel, the output will be as follows:

 

# fetch -qo - "http://localhost/manager/ispmgr?func=wwwdomain&out=xml"
<?xml version="1.0" encoding="UTF-8"?>
<doc>
	<elem>
		<name>foo.org</name>
		<owner>user</owner>
		<ssl/>
		<php/>
		<ssi/>
	</elem>
	<elem>
		<name>mydomain.com</name>
		<owner>user2</owner>
		<php/>
		<cgi/>
	</elem>
	<elem>
		<name>rotate.com</name>
		<owner>alm</owner>
		<ssl/>
		<php/>
	</elem>
	<elem>
		<name>test.com</name>
		<owner>john</owner>
		<php/>
		<cgi/>
	</elem>
	<elem>
		<name>test.net</name>
		<owner>user</owner>
	</elem>
</doc>

When calling a function that returns the element's parameters, for example, while editing or viewing this element, the control panel will return the XML document containing a list of XML-nodes corresponding to the element's parameter. For example, when viewing the WWW domain properties form, we'll see something like this:

# fetch -qo - "http://127.0.0.1/manager/ispmgr?func=wwwdomain.edit&elid=mydomain.com&out=xml"
<?xml version="1.0" encoding="UTF-8"?>
<doc>
	<elid>mydomain.com</elid>
	<domain>mydomain.com</domain>
	<alias>www.mydomain.com</alias>
	<ip>123.45.67.89</ip>
	<owner>user</owner>
	<admin>webmaster@mydomain.com</admin>
	<index>index.php index.htm</index>
	<php>phpcgi</php>
	<cgi/>
</doc>

When calling a function that performs an action, such as deletion of the WWW domain, the control panel will return a successful XML document:

# fetch -qo - "http://127.0.0.1/manager/ispmgr?func=wwwdomain.delete&elid=mydomain.com&out=xml"
<?xml version="1.0" encoding="UTF-8"?>
<doc>
	<ok>restart</ok>
</doc>

or the error message

# fetch -qo - "http://127.0.0.1/manager/ispmgr?func=wwwdomain.delete&elid=abrakadabra&out=xml"
<?xml version="1.0" encoding="UTF-8"?>
<doc>
	<error>abrakadabra not found.</error>
</doc>

Text output format

To receive data in a text format, add the out=text parameter to the control panel's query. The result will vary depending on a function you want to call. Thus, if receiving a list of elements, the function returns a list of strings, each string corresponding to an element and consisting of a set of parameters of that element. For example, when requesting a list of WWW domains, the result will be as follows :

# fetch -qo - "http://localhost/manager/ispmgr?func=wwwdomain&out=text"
name=foo.org owner=user ssl php ssi
name=mydomain.com owner=user2 php cgi
name=rotate.com owner=alm ssl php
name=test.com owner=john php cgi
name=test.net owner=user

When calling a function that returns a set of element's parameters, for example, when viewing or editing an element, the control panel will return a list of element's parameters, one per line. For example, when viewing the WWW domain properties form, we'll see:

# fetch -qo - "http://127.0.0.1/manager/ispmgr?func=wwwdomain.edit&elid=mydomain.com&out=text"
elid=mydomain.com
domain=mydomain.com
alias=www.mydomain.com
ip=123.45.67.89
owner=user
php=phpcgi
[email protected]
index=index.php index.htm
cgi

When calling a function that performs an action, such as deletion of a WWW domain, if a success the control panel will return

# fetch -qo - "http://127.0.0.1/manager/ispmgr?func=wwwdomain.delete&elid=mydomain.com&out=text"
OK


or the error message

# fetch -qo - "http://127.0.0.1/manager/ispmgr?func=wwwdomain.delete&elid=abrakadabra&out=text"
ERROR: abrakadabra not found.

Describing the functions

Functions are described according to the following structure:

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/manager/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.

Was this answer helpful?

 Print this Article

Also Read

How to easily create a site on the server with ISPmanager

Creating user Create a user who will own the site. ISPmanager --- Accounts...

Sheduler (cron) (ISPmanager)

ISPmanager allows automatic execution of scheduled jobs using Cron. Cron is a daemon that...

Configuring FTP-server

Supported software Currently ISPmanager supports the following FTP-servers: ProFTPd;...

Installation of ISPsystem software products from repository

ISPsystem's software products can be installed and updated using OS in-built tools, i.e. using OS...

Backup archives

In this module you can use a list of archives that were stored during the backup process. You can...