CommuniGate Pro
Версия 5.2
Программы
 
 
Помощники

Программы Помощники

Сервер CommuniGate Pro может использовать внешние программы для выполнения различных операций - сканирования сообщений, аутентификации пользователей, реализации политик входа RADIUS и т.д. Работа с этими внешними программами строиться одинаковым образом - они взаимодействуют с Сервером через простой протокол Интерфейса Помощника.

Более подробно об использовании внешних программ - Помощников вы можете узнать в разделе Администрирование Системы.

Протокол Помощников

Когда программа - Помощник запущена, Сервер отправляет команды процессу Помощника через стандартный ввод процесса. Сервер читает ответы программы из процесса стандартный вывод.

Команды и ответы являются текстовыми строками, оканчивающимся символом (символами) EOL, используемыми в ОС Сервера.

Каждая команда начинается с последовательного числа и ответ, выдаваемый программой - Помощником, также начинается с этого же числа. Этот метод позволяет программе - Помощнику обрабатывать несколько одновременных запросов и возвращать ответы в любом порядке.

Программа - Помощник может отправлять информационные ответы в любое время. Все информационные ответы начинаются с символа звездочка (*). Сервер игнорирует информационные ответы, но они могут появляться в Журнале работы Сервера.

Строки с ответами, созданные в программе - Помощнике, должны иметь размер не более чем 4096 байт.

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

Текущей директорией запущенной программы - Помощника является директория данных CommuniGate Pro.

Программы - Помощники не должны записывать ничего в своей поток стандартного вывода ошибок, за исключения случаев, когда им необходимо уведомить о причине сбоя перед аварийным завершением работы. CommuniGate Pro читает поток стандартного вывода ошибок только после завершения программы и, если программа записывала что-либо в этот поток во время обработки команды Сервера, то её работа может быть приостановлена операционной системой при переполнении буфера канала стандартного вывода ошибок.

Команда "Версия Интерфейса" используется для обеспечения совместимости между различными версиями программ - Помощников и различными версиями Сервера CommuniGate Pro. Сервер отправляет эту команду, указывая реализованную в нём версию протокола:
nnnnnn INTF serverInterfaceVersion
где:

nnnnnn
это уникальный последовательный номер этого запроса
serverInterfaceVersion
версия протокола Помощников, реализованная в этой версии Сервера CommuniGate Pro

Программа - Помощник должна вернуть ответ INTF и поддерживаемую версию протокола.
nnnnnn INTF programInterfaceVersion
Если возвращаемый номер меньше, чем версия протокола Сервера, то Сервер будет использовать эту (более старую) версию протокола.

Когда Сервер прекращает свою работу или когда ему необходимо остановить программу - Помощника, он отправляет команду QUIT и затем закрывает стандартный ввод процесса. Программа - Помощник должна отправить ответ OK и прекратить работу в течении 5 секунд.

Пример сессии (I: - команда сервера, отправленная на стандартный ввод программы, O: - ответы программы, записанные в её стандартный вывод, COMMAND - специальная команда Помощника):

O: * My Helper program started
I: 00001 INTF 1
O: 00001 INTF 1
I: 00002 COMMAND parameters
O: 00002 OK
I: 00003 COMMAND parameters
I: 00004 COMMAND parameters
O: * processing 00003 will take some time
O: 00004 ERROR description
O: 00003 OK
I: 00005 QUIT
O: * processed: 5 requests. Quitting.
O: 00005 OK
I: stdin closed

В примере выше показывается, что сервер не ждёт ответа для отправки следующей команды, и что он может принимать ответы от нескольких отправленных ранее команд в любом порядке - до тех пор, пока эти ответы приходят в течении указанного ограничения времени.


Внешняя Аутентификация

Программы для Внешней Аутентификации могут использоваться для проведения аутентификации, управления пользователями и оказания услуг маршрутизации с использованием внешних источников данных.

Протокол Интерфейса Внешнего Аутентификатора основывается на обычном Протоколе Помощников.

В этом руководстве описывается Версия 10 Интерфейса Внешнего Аутентификатора.

Когда пользователь должен быть аутентифицирован при помощи незащищённого (clear text) метода, Сервер отправляет следующую команду:
nnnnnn VRFY (mode) name@domain password [loginAddress]
где:

nnnnnn
это уникальный последовательный номер этого запроса
mode
имя услуги (IMAP, POP, FTP и т.д.), которая требует проведения этой операции аутентификации.
Этот параметр может отсутствовать, если запрос был получен от безымянного компонента Сервера.
Если имя услуги указывается, то оно заключается в скобки.
name
имя пользователя
domain
имя домена пользователя
password
проверяемая парольная строка. Если пароль содержит специальные символы, то он кодируется так же, как Строка в кавычках.
loginAddress
сетевой адрес, с которого входит пользователь.
Этот параметр может отсутствовать, если пароль проверяется внутренним компонентом Сервера.
Если параметр указывается, то он заключается в квадратные скобки.

Если пользователь должен быть аутентифицирован при помощи безопасного SASL метода, то отправляется следующая команда:
nnnnnn SASL(method) (mode) name@domain password key [loginAddress]
где:

method
имя безопасного SASL метода (CRAM-MD5, APOP)
key
строка challenge, отправляемая почтовой программе клиента. Если в challenge содержится специальный символ, он кодируется так же, как Строка в кавычках

Если пароль принимается, то Внешний Аутентификатор должен вернуть положительный ответ:
nnnnnn OK

Если пароль не принимается, то должен возвращаться отрицательный ответ:
nnnnnn ERROR optional-error-message

Если пароль принимается и есть аутентификационный ответ, который должен быть возвращён клиенту, то положительный ответ должен возвращаться как строка в кавычках:
nnnnnn RETURN "authentication-response"

проверка SASL пароля требует, что бы в программе Внешнего Аутентификатора все SASL методы и алгоритмы поддерживались корректно. Как альтернатива, программа Внешнего Аутентификатора может возвращать пароль пользователя в открытом виде, заставляя Сервер проверять пароль и расчитывать аутентификационные ответы. Пароль пользователя в открытом виде должен возвращаться как строка в кавычках:
nnnnnn PLAIN "plain-text-password"

Пример сессии (I: - команда сервера, отправленная на стандартный ввод программы, O: - ответы программы, записанные в её стандартный вывод):

I: 00001 INTF 1
O: 00001 INTF 1
I: 00010 VRFY user1@domain1.com dsyui134
O: 00010 OK
I: 00011 VRFY (IMAP) user2@domain2.com jskj23#45 [10.0.3.4]
O: 00011 ERROR incorrect password
I: 00012 SASL(CRAM-MD6) user4@domain2.com hdkj547812329394055 <pop-23456@mydomain.com> [10.0.1.4]
I: 00013 VRFY (IMAP) user2@domain2.com "jskj23\"45"
O: 00013 OK
O: 00012 ERROR unsupported SASL method
I: 00014 SASL(DIGEST-MD5) user4@domain2.com 012345 "user:qop:zz:mmm:uri" [10.0.1.4]
O: 00014 RETURN "0123456789AAAA"
I: 00015 SASL(DIGEST-MD5) user4@domain2.com 012345 "user:qop:zz:mmm:uri" [10.0.1.4]
O: 00015 PLAIN "my$$password"

Программа Внешней Аутентификации может использоваться для получения паролей в открытом виде из внешних баз данных.

Для того, что бы получить пароль, Сервер отправляет следующие команды:
nnnnnn READPLAIN name@domain
где:

name@domain
полное имя (адрес) требуемого Пользователя.

Программа должна возвращать пароль пользователя в открытом виде как строка в кавычках:
nnnnnn PLAIN "plain-text-password"
Если программа не может получить пароль в открытом виде, то она должна возвращать ответ FAILURE.

Программы Внешней Аутентификации могут также использоваться для обработки неизвестных имён. Например, программа может осуществлять поиск в внешней базе данных, проверяя, существует ли в этой базе данных пользователь, создавать Пользователя, Псевдоним, Группу, Список Рассылки или Переадресатор используя CLI/APICommuniGate Pro и возвращать Серверу положительный ответ. В этом случае CommuniGate Pro повторно попытается открыть объект с указанным именем в этом домене.

Для проверки неизвестного имени, Сервер отправляет следующие команды:
nnnnnn NEW name@domain relayType
где:

relayType
[MAIL] - если команда отправляется в процессе операции маршрутизации почты,
[SIGNAL] если команда отправляется в процессе операции маршрутизации сигналов,
[ACCESS] - если команда отправляется в процессе операции маршрутизации доступа.
name@domain
полное имя (адрес) неизвестного локального объекта.

Если программа отправляет ответ OK, то Сервер снова пытается найти объект name в Домене domain.

Если программа отправляет ответ ROUTED address, то Сервер берёт полученный address и перезапускает процедуру Маршрутизации с этим адресом. Маршрутизируемый адрес получает атрибут "can Relay", за исключением ситуации, если он был указан с префиксом [NORELAY].

Если программа отправляет ответ FAILURE, то Маршрутизатор Сервера возвращает код "временной внутренней ошибки" (этот код заставляет SMTP модуль вернуть код ошибки 4xx, а не код постоянной ошибки 5xx).

Если программа отправляет любой другой ответ, то Маршрутизатор Сервера возвращает ошибку "неизвестный пользователь".

Пример сессии:

I: 00010 NEW user1@domain1.com [MAIL]
O: 00010 ERROR this account is not known
I: 00011 NEW user2@domain2.com [MAIL]
I: 00012 NEW user3@domain2.com [ACCESS]
O: 00012 OK
O: 00011 ROUTED [NORELAY] userX@domain2.com

Установка Домена "Обратиться к Помощнику для Неизвестных" указывает серверу использовать программу Внешнего Аутентификатора при адресации неизвестного имени.

Программа Внешней Аутентификации может использоваться для помощи при Маршрутизации адреса. Если адрес направляется в домен @external, то "локальная часть" адреса передаётся Программе Внешней Аутентификации при помощи команды ROUTE:
nnnnnn ROUTE <address> relayType
где:

relayType
[MAIL] - если команда отправляется в процессе операции маршрутизации почты,
[SIGNAL] если команда отправляется в процессе операции маршрутизации сигналов,
[ACCESS] - если команда отправляется в процессе операции маршрутизации доступа.
address
локальная часть адреса с доменной частью external.

Если программа отправляет ответ ROUTED address, то Сервер берёт полученный address и перезапускает процедуру Маршрутизации с этим адресом. Маршрутизируемый адрес получает атрибут "can Relay", если он был указан с префиксом [RELAY].

Если программа отправляет ответ FAILURE, то Маршрутизатор Сервера возвращает код "временной внутренней ошибки" (этот код заставляет SMTP модуль вернуть код ошибки 4xx, а не код постоянной ошибки 5xx).

Если программа отправляет любой другой ответ, то Маршрутизатор Сервера возвращает ошибку "не могу провести маршрутизацию адреса".

Пример сессии:

I: 00010 ROUTE <user1> [MAIL]
O: 00010 ERROR this account is blocked
I: 00011 ROUTE <user2%domain1.dom> [MAIL]
I: 00012 ROUTE <"user3##name"%domain2.dom> [SIGNAL]
O: 00012 FAILURE internal error
O: 00011 ROUTED [RELAY] userX@domain100.dom

Программа Внешней Аутентификации может использоваться для помощи при операциях управления услугами. Если включена Установка Домена Обратиться к Помощнику для Регистраций, то Сервер отправляет следующие команды программе Внешней Аутентификации:

до создания Пользователя:
nnnnnn PRECREATE accountName@domainName accountType initialSettings
initialSettings является словарём.
Если эта операция заканчивается неуспешно, то Пользователь не создаётся.
после создания Пользователя:
nnnnnn POSTCREATE accountName@domainName accountType initialSettings
Если эта операция заканчивается неуспешно, то вновь созданный Пользователь удаляется.
до переименования Пользователя:
nnnnnn PRERENAME accountName@domainName newAccountName@newDomainName
Если эта операция заканчивается неуспешно, то Пользователь не переименовывается.
после переименования Пользователя:
nnnnnn POSTRENAME accountName@domainName newAccountName@newDomainName
Если эта операция заканчивается неуспешно, то Пользователь переименовывается обратно.
до удаления Пользователя:
nnnnnn PREDELETE accountName@domainName
Если эта операция заканчивается неуспешно, то Пользователь не удаляется.
после удаления Пользователя:
nnnnnn POSTDELETE accountName@domainName
до изменения Класса Лицензии Пользователя:
nnnnnn PRETYPECHANGE accountName@domainName newClass
Если эта операция заканчивается неуспешно, то Класс Лицензии Пользователя не изменяется.
после изменения Класса Лицензии Пользователя:
nnnnnn POSTTYPECHANGE accountName@domainName newClass
до обновления Установок Пользователя:
nnnnnn PREUPDATE accountName@domainName modifiedSettings
Если эта операция заканчивается неуспешно, то Установки Пользователя не изменяются.
после обновления Установок Пользователя:
nnnnnn POSTUPDATE accountName@domainName newSettings
до обновления пароля Пользователя:
nnnnnn PREPWDCHANGE accountName@domainName newPassword
Если эта операция заканчивается неуспешно, то пароль Пользователя не обновляется.
Пароль - это одна из Установок Пользователя; таким образом, за этой командой должна следовать команда PREUPDATE.

Программа должна либо отправить ответ OK, либо ответ FAILURE "errorCode".


Внешние Фильтры Сообщений

Программы - Внешние Фильтры Сообщений используются для фильтрования содержимого (от вирусов и спама).

Протокол Интерфейса Внешнего Фильтра основывается на обычном Протоколе Помощников.
В этом разделе описывается Версия 3 Протокола Внешнего Фильтра.

Если внешняя программа заканчивает свою работу аварийно, то CommuniGate Pro приостанавливает процесс Установки в Очередь до тех пор, пока внешняя программа не будет перезапущена.


Внешние Помощники RADIUS

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

Протокол Интерфейса Внешнего RADIUS основывается на обычном Протоколе Помощников.
В этом руководстве описывается Версия 2 Интерфейса Внешнего RADIUS.

Если Внешняя программа RADIUS включена, то она используется после того, как пароль пользователя прошёл проверку. Сервер отправляет ей следующие команды:
nnnnnn LOGIN name@domain attributes settings
где:

nnnnnn
это уникальный последовательный номер этого запроса
name
имя Пользователя
domain
имя Домена Пользователя
attributes
словарь со всеми затребованными атрибутами.
settings
словарь, в котором содержатся установки Пользователя.

Если запрос на вход принимается, то программа - Помощник должна вернуть положительный ответ:
nnnnnn ACCEPT attributes
где:

nnnnnn
последовательный номер запроса
attributes
словарь с атрибутами, добавляемыми в ответ RADIUS.

Если пароль не принимается, то должен возвращаться отрицательный ответ:
nnnnnn REJECT optional-error-message

Если Внешняя программа RADIUS включена, то она используется для обработки запросов Start, Stop и Interim-Update. Сервер отправляет следующие команды:
nnnnnn ACCNT command name@domain attributes
где:

nnnnnn
это уникальный последовательный номер этого запроса
command
команда (started, ended, updated)
name
имя Пользователя
domain
имя Домена Пользователя
attributes
словарь с требуемыми атрибутами.

Программа - Помощник должна возвращать положительный ответ:
nnnnnn OK
где:

nnnnnn
последовательный номер запроса

Атрибуты в словаре должны использовать цифровые значения как ключи (например, 27 для Session-Timeout).

Следующие атрибуты интерпретируются как 32-битные целые значения и закодированы в словаре как числовые строки:
NAS-Port, Service-Type, Framed-Protocol, Framed-Routing, Framed-MTU, Framed-Compression, Login-Service, Login-TCP-Port, Framed-IPX-Network, Session-Timeout, Idle-Timeout, Termination-Action, Framed-AppleTalk-Link, Framed-AppleTalk-Network, Event-Timestamp, NAS-Port-Type, Port-Limit, ARAP-Zone-Access, Password-Retry, Prompt, Tunnel-Type, Tunnel-Medium-Type, Tunnel-Preference, Acct-Interim-Interval, Acct-Delay-Time, Acct-Input-Octets, Acct-Output-Octets, Acct-Authentic, Acct-Session-Time, Acct-Input-Packets, Acct-Output-Packets, Acct-Terminate-Cause, Acct-Link-Count, Acct-Input-Gigawords, Acct-Output-Gigawords.

Следующие атрибуты интерпретируются как 32-битные IP адреса и кодируются в словаре как строки вида aaa.bbb.ccc.ddd:
NAS-IP-Address, Framed-IP-Address, Framed-IP-Netmask, Login-IP-Host.

Следующие атрибуты игнорируются в ответах Помощника:
User-Name, User-Password, CHAP-Password, State, Proxy-State, EAP-Message, Message-Authenticator, Acct-Status-Type.

Все другие значения атрибутов кодируются либо как Строка, либо как Блок Данных. Сервер использует формат блока данных для тех значений атрибутов, которые содержат байты не из диапазона 0x20-0x7F.
Формат Блока Данных должен использоваться, если значение содержит байты с двоичными нулями.

Если атрибут имеет несколько значений, то значение атрибута кодируется как Массив.

Следующие атрибуты добавляются к атрибутам словаря, передаваемым Помощнику:

0
Идентификатор запроса протокола RADIUS. Он может использоваться для обнаружения переданных повторно пакетов (дублирующихся запросов).
secretKey (только в запросах на аутентификацию)
значение строки с настройкой модуля RADIUS "общий секрет"
authData (только в запросах на аутентификацию)
16-байтный Блок Данных, содержащий часть "данных аутентификации" запроса RADIUS.

Зависимые от Производителя атрибуты представляются при помощи ключей с отрицательными цифровыми значениями. Абсолютное значение ключа является значением "VendorID". Для каждого VendorID, связанный с ним элемент является словарём. Ключи этого словаря являются зависимыми от Производителя "типами производителя", со связанными с ними "специфическими атрибутами". Значения "специфических атрибутов" могут хранится как Строка, Блоки Данных, Числа или Массивы Строк, Блоков Данных и/или Чисел.

Пример сессии (I: - команда сервера, отправленная на стандартный ввод программы, O: - ответы программы, записанные в её стандартный вывод):

I: 00001 INTF 1
O: 00001 OK 1
I: 00002 LOGIN user1@domain1.com {0=#15; 1="User1";4=10.0.0.1;32="NAS 1";31=4153837164;"-311"={9=#777;10="ZZZ";}; authData=[AbndghAbndgh1sjkjkss3T=]; secretKey=a123;} {RealName="User"; NATIP="192.168.1.3";}
O: 00002 ACCEPT {8=192.168.1.3; 9=255.255.255.0; 13=(0,3);}
I: 00003 LOGIN user1@domain1.com {0=#16; 1="uSEr1";32="NAS 2";31=415.5512.12; 8=192.168.1.3; authData=[Abnd278sjkljsljkjksFG=]; secretKey=a123;} {NATIP="10.0.1.114";}
O: 00003 REJECT
I: 00004 ACCNT started user1@domain1.com {0=#17;1="uSEr1";32="NAS 2";31=415.5512.12; 8=192.168.1.3;}
O: 00004 OK

Обратите внимание: Сервер может отправлять несколько параллельных запросов для одного Пользователя.

Обратите внимание: Внешняя программа RADIUS вызывается, когда данные Пользователя открыты. В системе с Динамическим Кластером это означает, что Внешние программы RADIUS должны запускаться на Backend Серверах и такие Внешние программы RADIUS, запущенные на других Backend Серверах, никогда не получат одновременные запросы для одного и того же Пользователя.


Внешние Обработчики CDR

Программы - Внешние Обработчики CDR могут использоваться для обработки CDR (Call Detail Records, Детализированная Информация о Звонках), созданных компонентом Signal при попытках установления звонка и его дальнейшей обработке. Они также могут обрабатывать CDR записи, созданные CG/PL приложениями.

Протокол Интерфейса Внешнего Обработчика CDR основывается на обычном Протоколе Помощников.
В этом руководстве описывается Версия 1 Интерфейса Внешнего Обработчика CDR.

Когда включена программа Внешний Обработчик CDR, то модуль Signal генерирует CDR и отправляет их в эту программу.

При создании CDR Сервер отправляет следующие команды:
nnnnnn CDR cdr_data
где:

nnnnnn
это уникальный последовательный номер этого запроса
cdr_data
CDR данные в формате компонента Signal или в формате CG/PL приложения.

когда запись обработана, программа должна вернуть положительный ответ:
nnnnnn OK


Внешняя Рекламная Система

Программы Внешней Рекламной Системы могут использоваться для обеспечения XIMSS клиентов "рекламными" данными (рекламной информацией, демонстрируемое клиентом пользователю).

Протокол Интерфейса Внешней Рекламной Системы основывается на обычном Протоколе Помощников.
В этом руководстве описывается Версия 1 Интерфейса Внешней Рекламной Системы.

Когда клиент запрашивает рекламное сообщение, Сервер отправляет следующие команды:
nnnnnn BANNER bannerType [ accountName@domainName ] [ INFO bannerSetting ] [ PREFS bannerPreference ] [ PARAM paramData ]
где:

nnnnnn
это уникальный последовательный номер этого запроса
bannerType
если строка с типом рекламного сообщения указана клиентским приложением (указано клиентское приложение и тип рекламного сообщения, например prontoEmailTop, myClientLeftBanner).
accountName@domainName
полное имя Пользователя, затребовавшего рекламное сообщение.
bannerSetting
(опционально) значение Установки Пользователя BannerInfo (Параметры Рекламы).
bannerPreference
(опционально) значение Настройки Пользователя BannerClass.
paramData
(опционально) текстовое представление объекта с параметрами, указанными клиентским приложением.

Когда запись обработана, программа должна вернуть положительный ответ:
nnnnnn RESULT resultData
где:

resultData
текстовое представление рекламной информации.

Программа также может вернуть блокирующий ответ:
nnnnnn BLOCK
Указанный bannerType добавляется в список "заблокированных" типов. Если клиент запрашивает рекламу "заблокированного" типа, то ему немедленно возвращается пустой ответ, при этом вызова программы Внешней Рекламной Системы не происходит.

Если программа Внешней Рекламной Системы не запущена, то любой запрос на рекламу возвращает пустой ответ.


Руководство CommuniGate® Pro. Copyright © 1998-2009, Stalker Software, Inc.