Создание удалённых API-скриптов для ISPConfig 3

Введение

Это руководство покажет, как создать API-скрипт для создания FTP-пользователя в ISPConfig 3. На примере функции sites_ftp_user_add вы получите знания, позволяющие писать скрипты для любой функции, доступной в ISPConfig 3.

Что получится в итоге

В результате вы получите рабочий PHP-скрипт, который логинится через SOAP в интерфейс удалённого API ISPConfig, формирует массив параметров на основе tform-файла и вызывает нужную функцию, например sites_ftp_user_add, а затем завершает сессию.

Основные файлы и пути

Файл с определением функций API: /usr/local/ispconfig/interface/lib/classes/remoting.inc.php
Tform-шаблоны для полей форм: обычно в каталоге ../sites/form/ (например ftp_user.tform.php)
Точка доступа SOAP: /remote/index.php или /ispconfig3/interface/web/remote/index.php в зависимости от установки

Важно: используйте полную структуру путей на вашем сервере и проверяйте права доступа у удалённого пользователя в панели ISPConfig (Система → Add Remote User).

Как распознать нужную функцию

Первый элемент при создании API-скрипта — это функция, которая добавляет запись в базу. Пример вызова функции из клиентского кода:

$domain_id = $client->sites_ftp_user_add($session_id, $client_id, $params_ftp);

Имя функции (в данном случае sites_ftp_user_add) вы найдёте в remoting.inc.php. В remoting.inc.php функция будет выглядеть примерно так:

?//* Add a record
    public function sites_ftp_user_add($session_id, $client_id, $params)
    {
        if(!$this->checkPerm($session_id, 'sites_ftp_user_add')) {
            $this->server->fault('permission_denied', 'You do not have the permissions to access this function.');
            return false;
        }
        return $this->insertQuery('../sites/form/ftp_user.tform.php',$client_id,$params);
    }

Эта запись показывает, что функция использует tform-шаблон ftp_user.tform.php — именно из него берутся имена и типы полей для $params.

Структура вызова функции — разбор строки

Возьмём строку:

$domain_id = $client->sites_ftp_user_add($session_id, $client_id, $params_ftp);

$domain_id — переменная для возвращаемого значения (можно оставить как есть).
$client-> — объект SOAP-клиента, менять не нужно.
sites_ftp_user_add — имя функции API, меняется в зависимости от требуемого действия.
($session_id, $client_id, $params_ftp) — аргументы; для разных функций набор аргументов может отличаться.

Как собрать массив параметров ($params)

Обычно массив начинается так:

$params = array( 'server_id'            => '1',
                            'parent_domain_id'        => $domain_id,
                            'username'            => $myusername,
                            'password'            => $mypassword,
                            'quota_size'            => '-1',
                            'active'            => 'y',
                            'uid'                => 'web'.$domain_id,
                            'gid'                => 'client'.$client_id,
                            'dir'                => '/var/www/clients/client'.$client_id.'/web'.$domain_id,
                            'quota_files'            => '100',
                            'ul_ratio'            => '-1',
                            'dl_ratio'            => '200',
                            'ul_bandwidth'            => '-1',
                            'dl_bandwidth'            => '100',);

Но имена и требования к полям зависят от tform-файла. Чтобы понять, какие ключи и какие значения допустимы, откройте ftp_user.tform.php или соответствующий файл, на который ссылается insertQuery.

Пример поиска файла шаблона (выполните на сервере):

sudo find / -name ftp_user.tform.php

Внутри tform-файла вы увидите определения полей в виде массивов с указанием ‘datatype’, ‘formtype’, ‘validators’ и т. п. Пример фрагмента:

'password' => array (
                'datatype'    => 'VARCHAR',
                'formtype'    => 'PASSWORD',
                'encryption' => 'CRYPT',
                'default'    => '',
                'value'        => '',
                'width'        => '30',
                'maxlength'    => '255'
            ),
            'quota_size' => array (
                'datatype'    => 'INTEGER',
                'formtype'    => 'TEXT',
                'validators'    => array (  0 => array (    'type'    => 'NOTEMPTY',
                                                'errmsg'=> 'quota_size_error_empty'),
                            1 => array (    'type'    => 'REGEX',
                                                'regex' => '/^(\-1|[0-9]{1,10})$/',
                                                'errmsg'=> 'quota_size_error_regex'),

Из этого видно, что для поля ‘password’ ожидается строка, а для ‘quota_size’ — целое число или -1.

Полный минимальный пример скрипта: вход, вызов, выход

Перед вызовом API убедитесь, что у вас создан Remote User в панели ISPConfig.

Настройка SOAP-адреса и учётных данных:

$username = 'yourusername';
$password = 'yourpassword';
/*
$soap_location = 'http://localhost:8080/ispconfig3/interface/web/remote/index.php';
$soap_uri = 'http://localhost:8080/ispconfig3/interface/web/remote/';
*/
$soap_location = 'http://localhost:8080/remote/index.php';
$soap_uri = 'http://localhost:8080/remote/';

Создание клиента, логин и вызов функции:

$client = new SoapClient(null, array('location' => $soap_location,
                                    
'uri'      => $soap_uri));
try {
    //* Login to the remote server
    if($session_id = $client->login($username,$password)) {
        echo 'Logged into remote server
sucessfully. The SessionID is '.$session_id.'  
';

Завершение работы и выход из сессии:

    //* Logout
    if($client->logout($session_id)) {
        echo "FTP Created";
    }
    
} catch (SoapFault $e) {
    die('SOAP Error: '.$e->getMessage());
    echo "Please contact the server administator";
}
?>;

Примечание: кодовые блоки оставлены в исходном виде. При вставке в реальный скрипт проверьте синтаксис, кавычки и завершение PHP-тега.

Часто используемые параметры FTP-пользователя — пояснения

server_id: ID сервера в ISPConfig (обычно 1).
parent_domain_id: ID домена/веб-сайта, к которому привязывается FTP-пользователь.
username / password: логин и пароль для FTP.
dir: домашняя директория FTP-пользователя (обычно /var/www/clients/client{N}/web{M}).
quota_size: дисковая квота в байтах или -1 для безлимита (смотрите validator в tform).
active: ‘y’/‘n’.
uid / gid: идентификаторы владельца и группы, часто формируются как web{domain_id} / client{client_id}.

Контрольные списки (роль: разработчик и администратор)

Для разработчика:
- Найти нужную функцию в remoting.inc.php.
- Открыть tform-файл указанной формы и определить ключи массива $params.
- Сформировать $params с корректными типами и значениями.
- Написать клиентский код с login → вызов → logout.
- Обработать SoapFault и логировать ответ сервера.
Для администратора:
- Создать Remote User в панели ISPConfig с нужными правами.
- Проверить корректность SOAP-URL и доступ по сети.
- Проверить права на директории, в которые будет записываться FTP-пользователь.
- Наблюдать логи ISPConfig при тестовом вызове.

Мини-методология: шаги при разработке нового API-скрипта

Определите требуемое действие и найдите соответствующую функцию в remoting.inc.php.
Прочитайте insertQuery(…, ‘…tform.php’, …) — откройте tform-файл и выпишите все поля и их требования.
Сформируйте массив $params с учётом типов и валидаторов.
Тестируйте локально: сперва ручной вызов через PHP-скрипт, затем интеграция в автоматизированные процессы.
Добавьте обработку ошибок и логирование ответа.

Когда этот подход не сработает / ограничения

Если у вашей установки ISPConfig кастомизированная структура и функции ссылаются на другие пути, вы должны адаптировать пути вручную.
Если удалённый пользователь не имеет прав на выполняемую операцию — функция вернёт ошибку permission_denied.
Если tform-файл содержит нестандартные валидаторы (например внешние зависимости), потребуется реализовать соответствующую логику до вызова API.

Отладка и распространённые ошибки

“permission_denied” — проверьте права Remote User в панели ISPConfig.
“SOAP Error” с сообщением о недоступности — проверьте URL, порт и наличие mod_soap/расширения SOAP в PHP.
Ошибки валидации — откройте tform и проверьте validators (NOTEMPTY, REGEX и т. п.).

Полезные команды:

Поиск tform-файла: sudo find / -name ftp_user.tform.php
Просмотр логов ISPConfig: tail -n 200 /var/log/ispconfig/ispconfig.log (путь может отличаться)

Критерии приёмки

Скрипт успешно логинится и получает session_id.
Скрипт вызывает нужную функцию без ошибок валидации.
FTP-пользователь появляется в панели ISPConfig и имеет ожидаемые параметры.
Скрипт корректно завершает сессию (logout) и логирует успешное завершение или ошибки.

Безопасность и права доступа

Храните учётные данные Remote User отдельно (например, в защищённом конфиге, не в репозитории).
Ограничьте права Remote User только необходимыми функциями.
При возможности используйте TLS/HTTPS для SOAP-эндпоинта.

Быстрый справочник (fact box)

Основной файл API: /usr/local/ispconfig/interface/lib/classes/remoting.inc.php
Tform-шаблоны: ../sites/form/*.tform.php
Команда поиска: sudo find / -name <имя_tform>.tform.php

Глоссарий (одна строка)

tform: PHP-массив, описывающий поля формы в ISPConfig, их типы и валидаторы.
remoting.inc.php: класс, который реализует удалённые (SOAP) интерфейсы API для ISPConfig.

Краткое резюме

Создание удалённого API-скрипта для ISPConfig сводится к трём шагам: найти нужную функцию в remoting.inc.php, изучить соответствующий tform-файл, сформировать $params и вызвать функцию через SOAP-клиент (login → call → logout). Следуйте чеклистам, проверяйте права и логи, и обрабатывайте SoapFault для надёжной автоматизации.

Важно: всегда тестируйте изменения в тестовой среде перед запуском на продакшене.

Как создать удалённые API-скрипты для ISPConfig 3