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

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

Интерфейс командной строки (CLI, Command Line Interface) — текстовый административный интерфейс сервера IVA Mail. Команды CLI принимает и выполняет модуль CMD сервера; это не команды операционной системы.

CLI удобен, когда нужно выполнять массовые операции, автоматизировать администрирование скриптами, проводить диагностику или управлять сервером, если панель администратора недоступна.

Описание всех команд приведено в разделе Справочник команд CLI.

Подключение и аутентификация

CLI работает по протоколу TCP. По умолчанию модуль CMD принимает подключения на порту 106.

Чтобы подключиться к CLI на сервере IVA Mail:

  1. Подключитесь к порту 106, например с помощью telnet:

    telnet 127.0.0.1 106

    Сервер ответит приветствием с кодом 200.

  2. Выполните аутентификацию под аккаунтом администратора:

    AUTH LOGIN postmaster@example.ru

    В ответ на запрос Password: введите пароль. После успешной аутентификации сервер выдаёт 200 authenticated as <аккаунт>.

Кроме LOGIN, модуль CMD поддерживает методы аутентификации PLAIN, APOP, CRAM-MD5 и DIGEST-MD5.

Чтобы завершить сеанс, выполните команду Quit.

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

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

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

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

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

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

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

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

Правила записи команд

Команда состоит из имени и параметров, разделённых пробелами. Имя команды пишется без кавычек, параметры передаются в формате JSON:

ModuleSetLogLevel "IMAP" 0
DomainSetSetting "example.ru" "Limits.MaxMessageSize" 10485760

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

Обозначение Значение

"text"

Строка в двойных кавычках.

123, null

Число и null пишутся без кавычек.

bIsOn

Логический параметр (true или false). Имя такого параметра начинается с b.

[…​]

Массив JSON, например ["key1","key2"].

{…​}

Объект (словарь) JSON, например {"LogLevel": 5}.

( …​ )

Необязательный параметр. Все параметры без скобок обязательны.

a|b

Один из вариантов, например "domName"|domUID — домен по имени или по UID.

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

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

MailQueueList ("moduleName" (start limit))

можно вызвать как MailQueueList, MailQueueList "SMTP" или MailQueueList "SMTP" 0 100.

Обращение к объектам по имени и UID

Домены, аккаунты и другие объекты можно указывать по имени или по числовому идентификатору UID. UID не меняется при переименовании объекта и однозначно указывает на него, если у объекта несколько имён.

DomainRemove "example.ru"
DomainRemove 57

UID можно узнать командами DomainGetID и ObjectGetID.

Во многих командах вместо домена можно передать null — тогда команда действует на уровне сервера или кластера. Это указано в описании конкретной команды.

Путь к настройке

Вложенную настройку можно указать массивом ключей или строкой с ключами через точку — обе записи равнозначны:

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

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

На каждую команду сервер отвечает строкой с кодом результата. Если команда возвращает данные, они выводятся после кода в формате JSON:

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

Команды, которые только изменяют состояние, возвращают код без данных, например 204 OK.

Вид вывода можно переключить служебными командами Inline (компактный или многострочный вывод), Ext (расширенный вывод) и NoEscape (экранирование служебных символов).

Как найти нужную команду

Имена команд строятся из названия объекта и действия, например DomainCreate, ModuleSetLogLevel, MailboxRename. Действие обычно обозначается так:

Часть имени Действие

List, Get, Read

Получение сведений.

Create, Add

Создание.

Set, Update

Изменение.

Del, Remove

Удаление.

Move, Rename

Перемещение и переименование.

Список команд с фильтром по имени выдаёт команда Help.

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

Команды …GetSetting, …SetSetting, …DelSetting и …UpdateConfig работают с настройками модулей, доменов и объектов, а команды Domains…Default и Accounts…Default — с умолчаниями.

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

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

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

Набор доступных команд зависит от административных прав аккаунта, под которым выполнена аутентификация: роли, уровня прав (сервер, кластер или домен) и области их действия. Некоторые команды доступны только администраторам сервера.

Если прав недостаточно, команда завершается ошибкой доступа. Текущие права соединения выдаёт команда MyRights.

Подробнее о правах см. Роли администрирования.

Типовые задачи

Задача Команды

Создать домен и изменить его настройку

DomainCreate, DomainSetSetting

Создать аккаунт и задать пароль

AccountCreate, AccountSetPassword

Изменить умолчания для аккаунтов домена или сервера

AccountsSetDefault, AccountsDelDefault

Изменить настройку аккаунта или другого объекта

ObjectSetSetting, ObjectDelSetting

Управлять составом группы

GroupAddAccount, GroupDelAccount

Изменить настройку модуля или уровень журнала

ModuleSetSetting, ModuleSetLogLevel

Посмотреть почтовую очередь и удалить письмо из неё

MailQueueList, MailQueueFail

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

ConnectionsList, LogsList

Управлять правилами обработки почты

RulesList, RuleAdd, RuleSet

Посмотреть и закрыть сессии пользователя

SessionList, AccountCloseSessions

Заблокировать IP-адрес

SetBlacklisted, DelBlacklisted

Запланировать задание

TaskSchedule, TasksList

Назначить администратора

AdminCreate, AdminsList

Проверить состояние кластера

ClusterGetImage, ClusterGetStats

Установить лицензию

LicenseRequest, LicenseInstall