IVA ДОКУМЕНТАЦИЯ
ОБНОВЛЕНИЯ

Интерфейс командной строки CLI

Интерфейс командной строки (CLI, Command Line Interface) предназначен для администрирования сервера IVA Mail без использования веб-интерфейса панели администратора.

CLI используется для:

  • выполнения административных команд;

  • настройки сервера, доменов, аккаунтов и модулей;

  • автоматизации повторяющихся операций;

  • диагностики состояния сервера;

  • работы со справочником, очередями, сессиями, правилами и другими объектами;

  • выполнения операций, которые удобнее запускать из скриптов.

CLI работает через модуль CMD. Подключение выполняется по TCP-соединению.

По умолчанию используется порт 106.

CLI IVA Mail не является командной оболочкой операционной системы. Это административный интерфейс сервера IVA Mail, доступный через модуль CMD.

Особенности CLI

Особенности CLI:

  • команды выполняются напрямую сервером IVA Mail;

  • команды не являются командами ОС Linux;

  • большинство операций возвращает JSON-структуры;

  • команды могут использовать имена объектов или UID объектов;

  • часть команд изменяет параметры сервера и объектов;

  • команды могут использоваться в автоматизации и скриптах.

Подключение к CLI

Для подключения к CLI выполните команду на сервере, где установлен IVA Mail:

telnet 127.0.0.1 106

После успешного подключения выполните аутентификацию:

auth login [login] [password]

где:

Параметр Описание

login

Логин аккаунта администратора сервера.

password

Пароль аккаунта администратора сервера.

Пример:

auth login postmaster admin
При первой аутентификации используйте данные аккаунта администратора, созданного при первоначальной установке сервера.

CLI и CMD

CLI и CMD относятся к разным уровням системы.

Термин Описание

CLI

Интерфейс командной строки, через который администратор вводит команды.

CMD

Серверный модуль IVA Mail, который принимает CLI-подключения и выполняет административные команды.

То есть администратор работает с CLI, а сервер обрабатывает эти команды через модуль CMD.

Когда использовать CLI

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

Сценарий Когда полезно использовать CLI

Массовые операции

Создание или изменение большого количества доменов, аккаунтов, групп или настроек.

Автоматизация

Выполнение команд из скриптов или систем автоматизации.

Диагностика

Получение информации о соединениях, потоках выполнения, очередях, журналах и состоянии модулей.

Аварийное администрирование

Работа с сервером при недоступности веб-интерфейса.

Настройка через шаблоны

Изменение параметров модулей, доменов, аккаунтов и профилей через JSON-структуры.

Интеграция

Выполнение административных операций из внешних систем.

Формат команд

Команда передается строкой без кавычек.

После имени команды через пробел указываются параметры.

Общий вид команды:

CommandName parameter1 parameter2 parameter3

Параметры передаются как текстовые представления JSON-объектов.

Например:

ModuleSetLogLevel "IMAP" 0

или:

DomainSetSetting "example.org" "Limits.MaxMessageSize" 10485760

Формат ответов

После выполнения команды сервер возвращает код результата.

Пример успешного ответа без данных:

204 OK

Некоторые команды возвращают данные:

DomainsList
200 OK
{
  "/N 3": "admin.dom",
  "/N 58": "example.org"
}

Команды, изменяющие состояние объекта, могут возвращать только код успешного выполнения.

Необязательные параметры

Необязательные параметры в описании команд указываются в круглых скобках:

ConnectionsList ("module_name" ("filter"))

Это означает, что команда может быть вызвана:

ConnectionsList

или с именем модуля:

ConnectionsList "IMAP"

или с именем модуля и фильтром:

ConnectionsList "IMAP" "127.0.0.1"

Альтернативные значения параметров

Если параметр может принимать несколько вариантов, они указываются через вертикальную черту |.

Например:

DomainRemove "string"|domainUID

Это означает, что домен можно указать:

  • по имени;

  • по числовому идентификатору UID.

Примеры:

DomainRemove "example.org"
DomainRemove 57

UID объектов

UID — это числовой идентификатор объекта.

UID используется для точного обращения к объекту, если:

  • имя объекта изменилось;

  • у объекта есть несколько имен;

  • нужно исключить неоднозначность;

  • команда поддерживает обращение как по имени, так и по UID.

Пример получения UID домена по имени:

DomainGetID "example.org"
200 OK
57

Пути к настройкам

Для обращения к вложенным настройкам можно использовать два варианта записи.

Вариант 1 — массив ключей:

["key1","key2","key3"]

Вариант 2 — строка с точечной нотацией:

"key1.key2.key3"

Обе записи могут использоваться для указания пути к настройке модуля или объекта.

Пример:

ModuleGetSetting "SMTPI" "Listener.MaxConnectionsPerAddress"

или:

ModuleGetSetting "SMTPI" ["Listener","MaxConnectionsPerAddress"]

Работа с JSON

Некоторые команды принимают или возвращают JSON-объекты.

JSON используется для:

  • передачи сложных настроек;

  • обновления конфигурации;

  • работы со списками;

  • описания объектов;

  • передачи параметров правил, профилей и справочников.

Пример JSON-объекта:

{
  "LogLevel": 5,
  "MaxChannels": 100
}

Пример JSON-массива:

[
  "key1",
  "key2",
  "key3"
]

Принципы именования команд

Имена CLI-команд обычно отражают тип выполняемой операции.

Префикс Назначение

List, Get, Read

Получение информации.

Create, Add

Создание объектов.

Set, Update

Изменение параметров или объектов.

Del, Remove

Удаление объектов или настроек.

Move, Rename

Перемещение или переименование объектов.

Примеры:

DomainsList
DomainCreate
ModuleSetLogLevel
DomainRemove
MailboxRename

Служебные команды CLI

CLI поддерживает служебные команды управления сессией.

Команда Назначение

INLINE

Переключает формат вывода между многострочным и компактным режимом.

NOTIMEOUT

Отключает тайм-аут чтения для CLI-соединения.

QUIT

Завершает CLI-сессию и закрывает соединение.

Права доступа CLI

CLI использует систему административных прав IVA Mail.

Доступность команд зависит от:

  • роли администратора;

  • уровня прав;

  • области действия прав.

Некоторые команды доступны только серверным администраторам.

При недостатке прав выполнение команды завершается ошибкой доступа.

Наследование настроек

Многие команды CLI работают с системой наследования настроек IVA Mail.

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

Порядок разрешения параметров:

  1. Локальное значение аккаунта.

  2. Профиль аккаунта домена.

  3. Профиль аккаунта сервера;

  4. Доменные умолчания для аккаунтов.

  5. Глобальные серверные умолчания для аккаунтов.

  6. Заводское значение.

Команды DelSetting и DelDefault не обязательно возвращают заводское значение. Вместо этого применяется ближайшее значение по цепочке наследования.

Подробнее см. в разделе Архитектура и наследование настроек.

Работа с настройками

CLI позволяет:

  • читать настройки модулей;

  • изменять параметры модулей;

  • изменять уровень журналирования;

  • управлять настройками доменов и аккаунтов;

  • возвращать параметры к значениям по умолчанию.

Для работы с настройками используются команды:

  • ModuleReadConfig;

  • ModuleGetSetting;

  • ModuleSetSetting;

  • ModuleDelSetting;

  • ModuleUpdateConfig;

  • DomainGetSetting;

  • DomainSetSetting;

  • ObjectGetSetting;

  • ObjectSetSetting.

Работа с доменами и объектами

CLI позволяет управлять:

  • доменами;

  • аккаунтами;

  • группами;

  • переадресаторами;

  • папками;

  • календарями;

  • контактами;

  • ролями и администраторами.

Большинство команд поддерживает обращение:

  • по имени объекта;

  • по UID объекта.

Работа с профилями настроек

CLI поддерживает создание и изменение профилей настроек.

Профили могут создаваться:

  • на уровне сервера;

  • на уровне домена.

Если вместо домена передается null, операция применяется к серверному уровню.

Пример:

AccountsDefaultProfileCreate null "default-profile"

Работа со справочником

CLI предоставляет команды для работы со справочником:

  • поиск записей;

  • добавление записей;

  • изменение атрибутов;

  • удаление записей;

  • перемещение записей.

Справочник может использовать разные источники данных:

  • PostgreSQL;

  • LDAP;

  • другие настроенные тома.

Для прямой работы с PostgreSQL используются команды PgDirectory*.

Для прямого обращения к LDAP используется команда LdapClientSearch.

Работа с правилами обработки почты

CLI позволяет управлять правилами обработки почты на уровнях:

  • сервера;

  • домена;

  • объекта.

Основные команды:

  • RulesList;

  • RuleGet;

  • RuleAdd;

  • RuleSet;

  • RuleDel.

Работа с очередями

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

Основные команды:

  • MailQueueList;

  • MailBatchList.

Работа с сессиями

CLI позволяет:

  • просматривать активные сессии;

  • создавать сессии;

  • закрывать сессии;

  • изменять данные сессий.

Основные команды:

  • SessionList;

  • SessionCreate;

  • SessionClose;

  • SessionGetInfo;

  • SessionUpdateInfo.

Работа с белыми и чёрными списками

CLI позволяет:

  • получать содержимое списков;

  • добавлять адреса;

  • удалять адреса.

Основные команды:

  • GetWhitelisted;

  • GetBlacklisted;

  • SetWhitelisted;

  • SetBlacklisted;

  • DelWhitelisted;

  • DelBlacklisted.

При добавлении адреса в белый список он автоматически удаляется из чёрного списка, и наоборот.

Работа со списками адресов

CLI поддерживает работу с именованными списками адресов.

Основные команды:

  • AddressListCheck;

  • AddressListGet;

  • AddressListUpdate.

Работа с календарями и контактами

CLI позволяет выполнять операции с календарями и контактами пользователей.

Для календарей доступны команды:

  • CalendarUpdate;

  • CalendarSearch;

  • CalendarShow;

  • CalendarSetAlarm;

  • CalendarFreeBusy;

  • CalendarProposal.

Для контактов доступны команды:

  • ContactsUpdate;

  • ContactsSearch;

  • ContactsRemove.

Работа с планировщиком задач

CLI поддерживает планирование и выполнение серверных задач.

Основные команды:

  • TaskSchedule;

  • TaskCancel;

  • TasksList.

Безопасность CLI

CLI предоставляет административный доступ к серверу IVA Mail.

Рекомендуется:

  • не открывать порт 106 во внешние сети;

  • использовать подключение только из доверенных сетей;

  • использовать SSH-туннель при удаленном подключении;

  • использовать сложные пароли администраторов;

  • выдавать только необходимые права администраторам;

  • учитывать, что часть команд изменяет состояние сервера немедленно.

Некоторые команды могут удалить объекты, изменить права доступа, изменить параметры доставки или остановить сервер. Перед выполнением команд рекомендуется проверять параметры и область применения.

Справочник команд

Данный раздел описывает:

  • общие принципы работы CLI;

  • синтаксис команд;

  • правила передачи параметров;

  • особенности наследования и прав доступа.

Подробное описание команд, параметров и примеров использования приведено в справочнике команд CLI.

Полный список CLI-команд приведен в разделе Справочник команд CLI.