CLI - Command Line Interface

Что такое CLI и зачем это нужно?

CLI-интерфейс почтового сервера CommuniGatePro является альтернативой стандартному веб-интерфейсу администрирования почтового домена. При грамотном использовании, являясь достаточно мощным и гибким инструментом, CLI позволяет в значительной мере автоматизировать многие элементы работы с почтой: создание и удаление пользователей, работа с листами рассылки, ведение статистики. Именно CLI-интейфейс используется нашей компанией для управления аккаунтами и доменами пользователей с сервера статистики. При заведении нового пользователя на почтовый сервер с использованием CLI-интерфейса отправляется соответствующая команда, создающая еще один почтовый ящик или домен. Аналогичные действия производятся в случае отключения пользователя.

Как работает CLI?

Общий принцип работы таков: клиент устанавливает TCP-соединение по определенному порту с почтовым сервером, проходит аутентификация пользователя, далее на каждый клиентский запрос сервер проверяет корректность запроса и наличие прав доступа на конкретный запрос у пользователя, а затем в зависимости от этого выдает определенный ответ клиенту. То есть сервер выполняет данные ему команды и возвращает результат или ошибку в диалоговом режиме.

Параметры подключения:

• сервер: mail.domain
• порт: 106
• имя пользователя: user@domain
• пароль: пароль, заданный для данного пользователя

Рассмотрим самый простой пример работы с CLI. В данном примере:

К: - клиент, С: - сервер

К: telnet mail.domain 106
С: 200 CommuniGate Pro PWD Server 3.5.9 ready
К: USER postmaster@domain
С: 300 please send the PASS
К: PASS postmasterpassword
С: 200 connected to backend server
К: CreateAccount "user1"
С: 200 OK
К: CreateAccount "user1"
С: 520 account with this name already exists
К: RenameAccount "user1" into "user2"
С: 200 OK
К: DeleteAccount "user2"
С: 200 OK
К: QUIT
С: 200 CommuniGate Pro PWD Server connection closed

В том случае, если к почтовому серверу через CLI подключается обычный пользователь почтового домена либо postmaster домена, работающего в базовом режиме (тарифный план "Экономный"), клиент получает доступ к следующей информации:

данные об аккаунте, например:

• GetAccountSettings accountName - получить информацию по установкам аккаунта
• GetAccountEffectiveSettings accountName - получить информацию по установкам аккаунта, включая установки по умолчанию
• GetAccountRules accountName - получить список фильтров данного аккаунта
• GetAccountInfo accountName Key keyName - информация по аккаунту. Например, время последнего логина
  keyName могут быть следующими:
  • LastAddress - IP-адрес, с которого в последний раз был осуществлен логин
  • LastFailedAddress - IP-адрес, с которого в последний раз была осуществлена неудачная попытка логина
  • LastLogin - дата и время последнего логина
  • LastFailedLogin - дата и время последней неудачной попытки логина
  • StorageUsed - размер (в байтах) дискового пространства, занимаемого данным аккаунтом

• LISTMAILBOXES accountName [ FILTER filter] [ AUTH authAccountName] - список папок пользователя
• DELETEMAILBOX accountName MAILBOX mailboxName [ AUTH authAccountName] - удаление папки

• GetAccountLists accountName - список листов рассылки данного пользователя
• ListSubscribers listName [ FILTER filter [ limit ] ] - список подписчиков листа рассылки данного пользователя

Если же почтовый домен работает в расширенном режиме, и через CLI к почтовому серверу подключается пользователь postmaster, ему становится доступна вся перечисленная выше информация о любом аккаунте плюс:

установки почтового домена, например:

• GetDomainSettings [ domainName ] - установки домена
• GetAccountDefaults [ domainName ] - установки по умолчанию для создаваемых пользователей домена
• ListAccounts [ domainName ] - список пользователей домена

• CreateAccount accountName [accountType] [ external ] [settings] - создание пользователя

• DeleteForwarder forwarderName - удаление frowarder'а

Для удобства работы с CLI и его интеграции в собственные программы пользователя или CGI-скрипты сайта разработчиками почтового сервера CommuniGatePro был создан специальный модуль языка Perl CLI.pm. Данный модуль содержит все необходимые процедуры для подключения через CLI к почтовому серверу, выполнения запросов и получения результатов.

Данный модуль уже установлен централизованно на серверах хостинга. Чтобы использовать функции данного модуля, подключайте его в своих скриптах следующим образом:

use CGP::CLI;

Для каждой команды CLI в данном модуле существует одноименная функция. Вызов выглядит примерно так:
my $subscribers=$cli->ListSubscribers("news", '', 100)
- в данном модуле используются следующие процедуры:

new CGP::CLI( { PeerAddr=>CGPaddress, PeerPort=>port, login=>username, password=>password, SecureLogin=>0})

Для подключения через CLI к почтовому серверу используются следующие параметры:

• CGPaddress: mail.domain
• port: 106
• username: user@domain, наиболее вероятно: postmaster@domain
• password: пароль пользователя user@domain
• SecureLogin: 0. Только если Вы включили опцию "Использовать шифрованную аутентификацию" в настройках аккаунта, используйте значение "1". В противном случае - пишите "0".

my $cli = new CGP::CLI( { PeerAddr => 'mail.domain',
                          PeerPort => 106,
                          login    => 'postmaster@domain',
                          password => 'password',
                          SecureLogin => 0 } )
   || die "Can't login to CGPro: ".$CGP::ERR_STRING."\n";

Logout
Закрывает текущую сессию с CLI. Возвращает TRUE в случае успеха или FALSE при каких-либо ошибках. Пример:

$cli->Logout();

getErrCode
Возвращает код последней выполненной CLI команды. Пример:

if($cli->getErrCode!=200) { print "Something's wrong..."; }

getErrMessage
Возвращает результат последней выполненной CLI команды в виде строки. Пример:

print "The last result message is ".$cli->getErrMessage."\n";

isSuccess
Проверяет, успешно ли выполнена последняя команда CLI. Возвращает TRUE в случае успеха (код 200) или FALSE при каких-либо ошибках. Пример:

if($cli->isSuccess) { print "OK"; }

getErrCommand
Возвращает полный текст последней отправленной серверу команды в виде строки.

NewPassword(newPassword)
Устанавливает новый пароль для текущего аккаунта.

SendCommand(command)
Отправляет команду серверу. Возвращает TRUE в случае успеха (код 200) или FALSE при каких-либо ошибках.

GetResponseData
Возвращает ссылку на данные (если они есть), полученные в результате выполнения SendCommand(command)

Примеры использования CLI.pm

Следующий скрипт на языке Perl позволяет получить список подписчиков листа рассылки:

#!/usr/local/bin/perl -w

use CGP::CLI;

my $cli = new CGP::CLI( { PeerAddr => 'mail.domain',
                          PeerPort => 106,
                          login    => 'postmaster@domain',
                          password => 'postmasterpassword',
                          SecureLogin => 0 } )

   || die "Can't login to CGPro: ".$CGP::ERR_STRING."\n";

 my $subscribers=$cli->ListSubscribers("ListName", '', 10000)
  || die "Can't list: ".$cli->getErrMessage.", quitting";
  print "  $_\n" foreach(@$subscribers);

Получаем список пользователей домена и время последнего логина для каждого из них:

#!/usr/local/bin/perl -w

use CGP::CLI;

my $cli = new CGP::CLI( { PeerAddr => 'mail.domain',
                          PeerPort => 106,
                          login    => 'postmaster@domain',
                          password => 'postmasterpassword',
                          SecureLogin => 0 } )

   || die "Can't login to CGPro: ".$CGP::ERR_STRING."\n";

my $accountList = $cli->ListAccounts("domain");

die "\nError " . $cli->getErrMessage . "(".$cli->getErrCode.
    ") fetching accounts list\n"
    unless ($accountList);

my $count = 0;

foreach $userName (sort keys %$accountList) {

print "Last login of user " . $userName . "\@domain: ";
print $cli->GetAccountInfo($userName . "\@domain", "LastLogin");
print "\n";

}

$cli->Logout;

О том, как правильно разместить собственный скрипт на виртуальном сервере, можно прочитать тут.

Вполне очевидно, что после изучения документации по доступным Вам CLI-командам Вы сможете реализовать совершенно новые функциональности и интергировать свой сайт с нужными элементами почтового сервера. Например, Вы можете реализовать автоматический сбор информации о подписчиках Ваших списков рассылки. Это может быть полезно для дальнейшего анализа таких данных или их резервного/архивного хранения.

Ссылки