Команды модуля MAIL.
Пред. | Глава 7. Протокол управления. | След.

## Команды модуля MAIL.

Команды описанные в этом разделе предназначены для работы с доменами и пользователями. Пользователю предоставляются такие функции как создание, удаление доменов и пользователей, получение и изменение различной связанной с ними информации и объектов.

### Команда LIST.

`LIST` { DOMAINS | USERS[:`domain`] } [{ START | END | CONTAIN }`"text"`] [`start` [`number`]]

`LIST` ALIASES { DOMAIN | USER } [`name[@domain]`]

Команда LIST доступна только администраторам и, с некоторыми ограничениями, операторам домена.

Первая форма команды запрашивает список доменов (первый аргумент - DOMAINS) или пользователей (первый аргумент - USERS). Если запрашивается список пользователей, то первый аргумент USERS может быть дополнен двоеточием и именем домена для которого необходимо получить список пользователей. Если домен не указан, то подразумевается домен в котором зарегистрирован текущий пользователь аутентифицированный командой AUTHENTICATE. Операторам домена допускается запрашивать только список пользователей и только собственного домена.

Следующий аргумент является необязательным и указывает фильтр имён получаемых объектов. Аргумент определяет в какой части имени объекта будет производиться регистронезависимый поиск подстроки указанной в параметре: START - имя должно начинаться с указанной подстроки, END - имя должно заканчиваться на указанную подстроку, CONTAIN - имя должно содержать указанную подстроку. В результат включаются только те элементы списка в именах которых найдена указанная подстрока.

Aргумент `start` позволяет запросить часть списка результата и задаёт индекс первого объекта с которого должен начинаться список. Первый объект имеет индекс 0. Необязательный аргумент `number` задаёт ограничение количества объектов результата.

Вторая форма команды запрашивает список псевдонимов домена (второй аргумент - DOMAIN) или пользователя (второй аргумент - USER). Третий необязательный аргумент указывает объект для которого запрашивается список псевдонимов - имя домена или пользователя. Если третий аргумент, либо его доменная часть опущены, то подразумевается текущий аутентифицированный пользователь или его домен. Операторам доменов доступен список псевдонимов только своего домена и списки псевдонимов пользователей только своего домена.

Результатом успешного выполнения команды являются ноль или более *-строк каждая из которых содержит имя объекта в кавычках. Вывод завершается ответом OK. Для списка пользователей домена (команда LIST USERS...) в *-строках результата после имени пользователя дополнительно указывается ограничение размера хранилища и объём использованного пространства в байтах, соответственно, во втором и третьем аргументах. Четвёртый аргумент - строка в кавычках в которой перечисляются флаги пользователя разделённые пробелом: OPER, ADMIN, HASH, DISABLED, LOCALCOPY, VCEDIT и BLACKHOLE.

### Команда CREATE.

`CREATE` DOMAIN `name`

`CREATE` USER `name[@domain]` [PASSWORD `"password"`] [FLAGS `"flag1 flag2 ... flag3"`] [LIMIT `"N [BYTE|BYTES|B|KB|K|MB|M|GB|G|TB|T]"`] [COPYTO "`addr@domain"`] [DEPTHMAX `N`]

`CREATE` ALIAS { DOMAIN | USER } `"name[@domain]"` `"alias"`

Команда CREATE доступна только администраторам и, с некоторыми ограничениями, операторам домена.

Первая форма команды создаёт новый домен с заданным именем и доступна только администраторам. В имени домена указанном во втором аргументе могут быть использованы любые допустимые для имени домена символы в кодировке UTF-8.

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

PASSWORD

  Устанавливает пароль.

FLAGS

  Устанавливает флаги пользователя которые перечисляются в строке в кавычках и разделяются пробелом: ADMIN - пользователь является администратором, OPER - пользователь является оператором домена (не имеет смысла в сочетании с ADMIN), HASH - на сервере будет храниться необратимо зашифрованный пароль (иначе, используется обратимое шифрование), LOCALCOPY - при пересылке сообщений на адрес указанный в свойстве COPYTO будут сохраняться локальные копии, VCEDIT - пользователю разрешено редактировать свою персональную информацию, BLACKHOLE - сообщения для пользователя будут успешно приниматься, но не будут сохранены.

  Операторы домена не могут указывать флаги ADMIN и OPER.

  Пользователи для которых установлен флаг HASH могут аутентифицироваться в сервисах только с использованием передачи открытого пароля. Для таких пользователей становится особенно критичным использование защищённых соединений.

LIMIT

  Устанавливает ограничение на объём ресурса пользователя на хранилище. Значение задаётся целым положительным числом с необязательным указанием размерности. Размерность по-умолчанию - байты. Отсутствие этого свойства или значение 0 означает отсутствие ограничения на объём ресурса.

COPYTO

  Адрес электронной почты на который будут отправляться входящие сообщения пользователя. См. флаг LOCALCOPY.

DEPTHMAX

  Устанавливает ограничение на глубину вложенности папок (или «почтовых ящиков» в терминах `IMAP`) которые может создавать пользователь. Отсутствие этого свойства или значение 0 означает отсутствие ограничения.

Третья форма команды создаёт новый псевдоним домена (второй аргумент - DOMAIN) или пользователя (второй аргумент - USER) имя которого указано в третьем аргументе. Имя нового псевдонима указывается в четвёртом аргументе. Операторы домена могут создавать только псевдонимы пользователей и только в своём домене.

### Команда DELETE.

`DELETE` { DOMAIN | USER } `"name[@domain]"`

`DELETE` ALIAS { DOMAIN | USER } `"name[@domain]"` `"alias"`

Команда DELETE доступна только администраторам и, с некоторыми ограничениями, операторам домена.

Первая форма команды удаляет домен (первый аргумент - DOMAIN) или пользователя (первый аргумент - USER) имя которого указано во втором аргументе. Операторы домена могут удалять только пользователей своего домена для которых не установлен флаг OPER или ADMIN.

Вторая форма команды удаляет псевдоним домена (второй аргумент - DOMAIN) или пользователя (второй аргумент - USER) имя которого указано в третьем аргументе. Имя удаляемого псевдонима указывается в четвёртом аргументе. Операторы домена могут удалять только псевдонимы пользователей и только в своём домене.

### Команда SET.

`SET` DOMAIN [ `"name"` [DKIM-MODE { OFF | KEY | DELEGATE }] [DKIM-SELECTOR `"selector"`] [DKIM-SDID `"sdid"` ] ]

`SET` USER [ `"name[@domain]"` [PASSWORD `"password"`] [FLAGS `"flag1 flag2 ... flag3"` ] [LIMIT `"N [BYTE|BYTES|B|KB|K|MB|M|GB|G|TB|T]"`] [COPYTO `"addr@domain3"`] [DEPTHMAX `N`] ]

Первая форма команды запрашивает либо устанавливает свойства подписи DKIM для писем отправляемых пользователями домена `name` и доступна только администраторам. Второй аргумент `name` может быть именем домена, либо псевдонимом. Если аргументы после `name` не указаны, в ответ на команду будет передан ряд *-строк описывающих текущие свойства. Если аргумент `name` опущен, подразумевается домен текущего пользователя. Первый аргумент *-строк ответа указывает свойство, второй - значение этого свойства. Далее перечислены возвращаемые свойства и их значения:

`DOMAIN`

  Основное имя домена.

`DKIM-MODE`

  Режим подписи DKIM. Второй аргумент имеет одно из трёх начений: `OFF` - подпись не используется, `KEY` - для подписи используется приватный ключ установленный для данного домена, `DELEGATE` - для подписи будут использоваться приватный ключ и SELECTOR локального домена имя которого указано в свойстве DKIM-SDID.

`DKIM-SDID`

  Это свойство не указывается если свойство DKIM-MODE имеет значение `OFF`.

  Если свойство DKIM-MODE имеет значение `KEY`: Signing Domain IDentifier. Имя домена отвечающего за подпись. Это имя указывается в теге "d=" подписи. См. RFC 5585, 1.1. DKIM's Scope.

  Если свойство DKIM-MODE имеет значение `DELEGATE`: Имя локального домена которому делегируется создание подписей.

`DKIM-SELECTOR`

  Это свойство указывается если свойство DKIM-MODE имеет значение `KEY`.

  Селектор указывающий на публичный ключ опубликованный в DNS. См. RFC 5585, 4.3. The Selector Construct.

`DKIM-PRIVKEY-INSTALLED`

  Это свойство указывается если свойство DKIM-MODE имеет значение `KEY`.

  Значение `YES` означает что приватный ключ установлен и для почтовых сообщений будет устанавливаться подпись DKIM. Если приватный ключ ещё не был установлен, данное свойство будет иметь значение `NO`. Для установки приватного ключа используется команда DKIM-KEY.

Если для команды SET с первым аргументом DOMAIN указано больше двух аргументов, то аргументы следующие за `name` имеют тот же смысл что и соответствующие свойства получаемые в *-строках ответа описанных выше.

Вторая форма команды запрашивает либо устанавливает свойства пользователя имя которого указано во втором аргументе. Второй аргумент `name` может быть именем пользователя, либо его псевдонимом. Если в имени отсутствует доменная часть, то используется домен текущего пользователя. Если аргументы после `name` не указаны, в ответ на команду будет передан ряд *-строк описывающих текущие свойства. Если аргумент `name` опущен, подразумевается текущий пользователь. Первый аргумент *-строк ответа указывает свойство, второй - значение этого свойства. Далее перечислены возвращаемые свойства и их значения:

`USER`

  Полное имя пользователя.

`FLAGS`

  Строка в кавычках содержащая список флагов пользователя разделённых пробелом.

`LIMIT`

  Ограничение объёма хранилища пользователя в байтах. Значение 0 означает отсутствие ограничения.

`USED`

  Занятый объём хранилища пользователя в байтах.

`COPYTO`

  Адрес электронной почты на который будут отправляться входящие сообщения пользователя. См. флаг LOCALCOPY

`DEPTHMAX`

  Ограничение на глубину вложенности папок (или «почтовых ящиков» в терминах `IMAP`) которые может создавать пользователь. Значение 0 означает отсутствие ограничения.

`LOGINTIME`

  Дата и время последней успешной аутентификации пользователя в формате YYYY-MM-DD HH:MM:SS, где: YYYY - год, MM - месяц, DD - день месяца, HH:MM:SS - время (часы:минуты:секунды).

  Это свойство указывается только если пользователь был хотя бы раз успешно аутентифицирован.

Если для команды SET с первым аргументом USER указано больше двух аргументов, то аргументы FLAGS, LIMIT, COPYTO и DEPTHMAX следующие за `name[@domain]` имеют тот же смысл что и соответствующие свойства получаемые в *-строках ответа описанных выше.

Значение аргрумента LIMIT задаётся целым положительным числом с необязательным указанием размерности. Размерность по-умолчанию - байты.

Аргумент PASSWORD устанавливает новый пароль для пользователя. Пароль должен удовлетворять требованиям к сложности заданным конфигурацией, в противном случае изменения не будут приняты и результатом выполнения команды будет ответ сервера `NO (TOO-WEAK-PSWD) "The password is not strong enough"`. При успешной установке пароля, OK-строка ответа сервера будет содержать одно из значений в первом аргументе в круглых скобках:

`WEAK-PSWD`

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

`GOOD-PSWD`

  Достаточная сложность пароля.

`STRONG-PSWD`

  Надёжный пароль.

Пользователи не имеющие флагов OPER или ADMIN могут только запрашивать и только собственные свойства. Исключение - свойство PASSWORD, пользователь может устанавливать свой пароль. Операторы доменов могут запрашивать и устанавливать свойства пользователей только своего домена, если это не администраторы или операторы домена.

### Команда DKIM-KEY.

`DKIM-KEY` `domain` PUBLIC

`DKIM-KEY` `domain` SET {`"password"`} {`data`}

`DKIM-KEY` `domain` { GENERATE:1024 | GENERATE:2048 } [`"password"`]

Команда DKIM-SET в первой форме доступна операторам домена и администраторам, во второй и третьей формах - только администраторам.

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

Вторая форма команды устанавливает для домена указанного в первом аргументе приватный ключ переданный в червёртом аргументе в виде лиерала. Третий аргумент задаёт пароль для устанавливаемого ключа. Если пароль не требуется, в третьем аргументе следует указать пустую строку `""`.

Третья форма команды запрашивает генерацию приватного ключа сервером и его установку для домена указанного в первом аргументе. Второй аргумент задаёт длину генерируемого ключа: GENERATE:1024 - длинна ключа 1024 бита, GENERATE:2048 - длинна ключа 2048. Если указан третий аргумент, генерируемый ключ будет защищён заданным паролем.

### Команда SUBST.

`SUBST` `domain` LIST [`id`]

`SUBST` `domain` CREATE {`"pattern"`} [POS `N`] [PRIVATE { ON | OFF }]

`SUBST` `domain` DELETE {`id`}

`SUBST` `domain` CHANGE {`id`} [PATTERN "`pattern"`] [POS `N`] [PRIVATE { ON | OFF }]

`SUBST` `domain` { INSERT | REMOVE } {`id`} { `name` | `address` }

Команда SUBST предназначена для работы со списками подстановок домена и доступна администраторам и операторам. Операторы домена могут применять команду SUBST только для своего домена. Все формы команды в первом аргументе содержат имя домена над подстановками которого производятся действия.

Каждая запись списка подстановок домена имеет уникальный идентификатор `id` (положительное число больше 0), шаблон имени пользователя `pattern` (части адреса электронной почты до символа '@'), признак "приватный" и список адресов электронной почты и/или имён пользователей домена указанного первым аргументом.

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

В первом случае (`id` не указан), при успешном выполнении команды, список подстановок домена передаётся сервером в *-строках. В первом аргументе каждой такой строки указывается идентификатор подстановки, во втором - символ "1" для приватной подстановки или "0" для публичной, в третьем аргументе указывается шаблон в кавычках. Список заканчивается ответом OK.

Во втором случае (`id` указан), в *-строках ответа с одним аргументом перечисляются имена (адреса) списка подстановки заключённые в кавычки. Список заканчивается ответом OK с двумя аргументами: в первом - символ "1" для приватной подстановки или "0" для публичной, во втором - шаблон подстановки в кавычках.

Вторая форма команды создаёт новую подстановку в домене указанном в первом аргументе. Третий аргумент задаёт шаблон. Остальные аргументы необязательные: POS - позиция в списке куда будет помещена созданная подстановка (первая запись имеет позицию 0), по-умолчанию подстановка помещается в конец списка, PRIVATE - признак приватности указанный значением следующего аргумента. Значение для PRIVATE - один из регистронезавимых синонимов: `1`, `ENABLE`, `YES`, `ON`, `TRUE` - приватная подстановка, `0`, `DISABLE`, `NO`, `OFF`, `FALSE` - публичная подстановка.

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

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

Четвёртая форма команды изменяет существующую подстановку домена указанного в первом аргументе идентификатор которой указан в третьем аргументе. Изменения задаются значениями аргументов PATTERN, POS и PRIVATE по аналогии с описаниями выше.

Пятая форма команды добавляет (второй аргумент INSERT) или удаляет (второй аргумент REMOVE) имя пользователя домена или адрес электронной почты указанный в четвёртом аргументе в подстановку домена указанного в первом аргументе. Идентификатор подстановки указывается в третьем аргументе.

### Команда VCARD.

`VCARD` [`name[@domain]` [`data`]]

Команда VCARD позволяет установить или получить личную информацию пользователя в формате vCard версии 4.0 (RFC 6350). Все пользователи могут запрашивать vCard любых пользователей. Обычные пользователи могут устанавливать vCard только для своей учётной записи только если для пользователя установлен флаг VCARD. `Операторы домена` могут устанавливать vCard только для пользователей своего домена если они не являются операторами домена или администраторами.

Если второй аргумент не указан, подразумевается запрос vCard пользователя указанного в первом аргументе. Если в первом аргументе опущена доменная часть, подразумевается домен текущего пользователя. Команда отправленная без аргументов запрашивает vCard текущего, т.е. аутентифицированного в сеансе MMP пользователя. При успешном выполнении команды сервер отправляет ответ OK с одним аргументом - данными в формате vCard в виде литерала.

Для установки vCard должно быть указано оба аргумента. Второй аргумент указывается в виде литерала.

### Команда LOG.

`LOG` [`stop-id`]

Команда LOG позволяет получить последние записи журнала и доступна только администраторам.

Сервер хранит установленное конфигурацией количество последних записей журнала. Каждой такой записи присваивается числовой идентификатор - положительное целое число которое увеличивается на единицу перед каждом присвоением.

В ответ на команду сервер отправляет ноль или более *-строк каждая из которых имеет один аргумент - строка в кавычках содержащая запись журнала. Записи перечисляются начиная с последней (самой новой). Перечисление заканчивается когда выданы все хранимые записи или когда достигнута запись с идентификатором который указан необязательным аргументом `stop-id`. В последнем случае запись с идентификатором `stop-id` не включается в результат. Ответ заканчивается OK-строкой с двумя аргументами. Первый - идентификатор первой выданной записи. Во втором аргументе указывается 1 если вывод записей остановился перед записью с идентификатором `stop-id`, или 0 если выданы все хранящиеся записи.

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

    1. Присвоить ID = "0"
    2. Отправить команду - результат объединения строки "LOG " и значения переменной ID.
    3. Получить записи в *-ответах и отправить на консоль пользователя в обратном порядке.
    4. Получить ответ OK. Если второй аргумент ответа "0" И ID<>"0" -
    отправить в консоль уведомление о том что некоторое количество записей потеряно.
    5. Присвоить ID значение первого аргумента полученного ответа OK.
    6. Ожидать таймаут.
    7. Перейти ко второй строке данного сценария.

Пред. | Наверх | След.
Команды управления сеансом. | Начало | Команды модуля AB.