В статье описаны методы вызова функций панели управления с помощью API.
Авторизация обязательна перед вызовом функций панели управления.
Этот метод наиболее подходит для использования панели управления через браузер или для скриптов, которые обращаются к ней неоднократно.
Авторизация происходит путём обращения по следующему URL:
https://IP-адрес:1500/ispmgr?out=xml&func=auth&username=имя_пользователя&password=пароль
После этого панель управления вернёт либо сообщение об ошибке, либо XML-документ следующего вида:
<?xml version="1.0" encoding="UTF-8"?>
<doc ...>
<auth id="номер сессии" level="уровень доступа">номер сессии</auth>
...
</doc>
Сессия привязывается к IP-адресу. В дальнейшем необходимо передавать полученный номер сессии с каждым запросом к панели управления в параметре "auth":
https://IP-адрес:1500/ispmgr?auth=номер_сессии&out=xml&func=функция&параметр1=значение&параметр2=значение...
Номер сессии хранится в течение часа со времени последнего запроса. Если в течение часа не было выполнено никаких запросов, необходимо заново пройти авторизацию.
Уровень доступа определяет права, с которыми авторизовался пользователь. Рекомендуется проверять его на соответствие ожидаемому, чтоб избежать возможных недоразумений в дальнейшей работе скрипта.
Этот метод авторизации удобен для удалённого единичного обращения к панели управления. В отличии от предыдущего примера, вместо параметра "auth" с номером сессии можно передать параметр "authinfo" и указать в нём сразу имя пользователя и пароль, под которыми будет выполнена операция, например:
https://IP-адрес:1500/ispmgr?authinfo=admin1:mypasswd&out=xml&func=функция&параметр1=значение&параметр2=значение...
Этот метод авторизации является разовым, то есть необходимо передавать параметр "authinfo" с каждым запросом к панели управления.
Авторизацию через "authinfo" можно ограничить "белым списком" IP-адресов и/или сетей. "Белый список" можно настроить через параметры "RestrictAuthinfoRange" и "Option RestrictAuthinfo" конфигурационного файла или через настройки авторизации.
Используется для реализации сквозной авторизации пользователя в панели управления из других систем провайдера при помощи только логина или пароля администратора.
Если клиент идентифицирован внешним скриптом, например, билинговой системой, и его необходимо перенаправить в панель управления, минуя шаг авторизации. Для этого скрипт должен сгенерировать секретный ключ (любая строка, не менее 16 символов длиной).
Например, получили строку "1234567890qwertyuiop".
Пользователь, под которым необходимо авторизоваться, имеет логин "vasya".
Авторизациионные данные администратора ispmanager, например пользователь "root" с паролем "secret".
Далее скрипту необходимо выполнить следующий запрос:
https://URL/ispmgr?out=xml&authinfo=root:secret&func=session.newkey&username=vasya&key=1234567890qwertyuiop
В ответ будет либо "ok", либо ошибка.
Если получен "ok", то пользователя, которого нужно авторизовать, необходимо перенаправить на следующий URL:
https://URL/ispmgr?func=auth&username=vasya&key=1234567890qwertyuiop&checkcookie=no
После перехода по данному URL пользователь будет авторизован в панели управления, а ключ удалён.
Задание ключа возможно с любого IP-адреса. IP-адрес не привязывается к номеру сессии. Ключ действителен один раз. Ограничение на вход с определённых IP-адресов не учитывается.
Поддерживаются методы "GET" и "POST".
Обращение к какой-либо функции панели управления с правами другого пользователя осуществляется путём добавления к URL дополнительного параметра "su=имя_пользователя". Администратор сервера может вызывать функции с правами любых пользователей, реселлер — только с правами своих пользователей. Для всех остальных эта возможность запрещена.
Получение результатов выполнения функции или ошибки на родном языке осуществляется путём добавления к URL дополнительного параметра "lang", например "lang=ru" или "lang=en". В случае, если указан несуществующий язык, то будет использован язык, который используется в панели управления по умолчанию.
Панель управления предоставляет возможность получения результата выполнения своих функций в формате XML, текстовом формате и в формате JSON. Указание желаемого параметра осуществляется путём добавления дополнительного параметра "out=имя_формата".
Возможные значения параметра out:
Если параметр "out" отсутствует, то считается, что данные предназначены для браузера и они преобразуются в html.
При локальных обращениях к панели управления из скриптов или shell удобнее всего пользоваться утилитой "mgrctl", которая имеет ряд преимуществ:
В качестве примера рассматривается получение списка сайтов. Все остальные функции можно вызывать аналогичным образом.
curl -k -s "https://IP-адрес/ispmgr?authinfo=логин:пароль&out=xml&func=webdomain"
/usr/local/mgr5/sbin/mgrctl -m ispmgr webdomain
Для обращения по URL из Perl необходимо установить библиотеку LWP. Для работы с XML-документами требуется библиотека XML::LibXML.
#!/usr/bin/perl -w
use CGI::Carp qw(fatalsToBrowser);
print "Content-type: text/html\n\n";
use LWP::UserAgent;
use XML::LibXML;
my $result;
# Создадим псевдоброузер, который будет "притворяться" MSIE и отправим запрос
$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-адрес/ispmgr');
$req->content("authinfo=логин:пароль&out=xml&func=webdomain");
my $res = $ua->request($req);
# Проверим результат
if ($res->is_success) {
$result = $res->content;
} else {
die $res->status_line."\n";
}
# После этого переменная $result содержит XML документ со списком WWW доменов,
# либо сообщение об ошибке
my $parser = XML::LibXML->new();
my $doc = $parser->parse_string( $result );
my $root = $doc->documentElement();
# Получим список имён WWW доменов
my @sites = ();
for( $root->findnodes( "elem/name" ) ){
push @sites, $_->textContent;
}
# выведем результат на экран
for( sort @sites ){
print $_."<br>\n";
}
Язык PHP предоставляет возможность работы с URL как со стандартными файлами. Для обработки XML-документов используется библиотека "DOM XML".
<?php
$result = "";
$fh = fopen( "http://IP-ADDR/ispmgr?authinfo=логин:пароль&out=xml&func=wwwdomain", "r" );
while( $data = fread( $fh, 4096 ) ){
$result .= $data;
}
fclose( $fh );
// После этого переменная $result содержит XML-документ со списком WWW-доменов,
// либо сообщение об ошибке
$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";
}
}
}
}
?>
Для обращения по URL из Python используется, например, библиотека "urllib2". Для работы с XML-документами — библиотека "xml.dom.minidom".
#!/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=логин:пароль&func=wwwdomain&out=xml')
# После этого переменная res содержит XML-документ со списком WWW-доменов,
# либо сообщение об ошибке
xmldoc = minidom.parse(res)
# Получим список имён WWW-доменов и выводим его результат на экран
for node in xmldoc.getElementsByTagName('elem'):
for name in node.getElementsByTagName('name'):
print ('%s<br>' % name.firstChild.nodeValue)
Описание запроса выглядит следующим образом:
Функция: имя функции, которое необходимо передать в параметре "func" запроса.
Параметры: список параметров с кратким описанием. Если функция не принимает никаких параметров, они не указываются в описании. Параметры передаются в формате параметр=значение.
Пример команды
/usr/local/mgr5/sbin/mgrctl -m ispmgr db.users elid="user2->MySQL" sok=ok
Результат: бывает несколько видов результата в зависимости от типа запрашиваемой функции:
В этом случае XML-документ имеет следующий вид:
<?xml version="1.0" encoding="UTF-8"?>
<doc>
<elem>параметры элемента в списке</elem>
<elem>параметры элемента в списке</elem>
...
<elem>параметры элемента в списке</elem>
</doc>
В качестве результата функции описываются только параметры элемента в списке, которые представляют собой один или несколько XML-узлов с возможными атрибутами и значениями, так как всё остальное идентично для всех видов списков элементов. Например:
<?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>
В этом случае XML-документ имеет вид:
<?xml version="1.0" encoding="UTF-8"?>
<doc>
<elid>уникальный идентификатор объекта</elid>
параметры объекта
</doc>
В качестве результата функции описываются только параметры объекта. Параметры объекта представляют собой один или несколько XML-узлов с возможными атрибутами и значениями, описывающие свойства данного объекта. Всё остальное идентично для всех видов списков элементов.
Например:
<?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>
Данный результат выдаётся при создании, изменении, удалении, включении или выключении объекта. В этом случае XML-документ имеет следующий вид:
<?xml version="1.0" encoding="UTF-8"?>
<doc>
<ok/>
</doc>
Данный результат выдаётся при возникновении ошибки в процессе обработки запроса. В этом случае XML-документ имеет следующий вид:
<?xml version="1.0" encoding="UTF-8"?>
<doc>
<error type="exists" object="user" lang="ru">
<param name="object" type="msg" msg="Пользователь">user</param>
<param name="value">ben</param>
<stack>
<action level="30" user="jen">admin.edit</action>
</stack>
<group>__object__ со значением '__value__' уже существует</group>
<msg>Пользователь со значением 'ben' уже существует</msg>
</error>
</doc>
Описание функций и их параметров панели управления см. в статье ispmanager API.
Также актуальная информация доступна на мастер-сервере.
Получение полного списка функций ispmanager:
/usr/local/mgr5/sbin/mgrctl -m ispmgr -i
Получение описания данных вывода списка пользователей (можно использовать параметр "lang" для выбора языка):
/usr/local/mgr5/sbin/mgrctl -m ispmgr -i user lang=ru
Самый простой способ составить API запрос — выполнить требуемое действие в интерфейсе панели и посмотреть функцию и параметры в логе:
1. Откройте лог-файл панели с помощью команды tail:
tail -f /usr/local/mgr5/var/ispmgr.log | grep Request
2. Выполните требуемое действие в интерфейсе панели. При этом в открытом лог-файле будет видна выполняемая функция и её параметры (подсвечивается зелёным цветом, начинается с INFO Request).
Например, создание доменного имени (DNS) в логе ispmanager выглядит следующим образом:
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. На основе полученной в логе функции составьте API-запрос. API-запрос всегда имеет формат "https://
Исключив необязательные параметры из запроса ("sfrom", "clicked_button", "operafake", "progressid", параметры равные знаку * и параметры с пустыми значениями), получим API-запрос:
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