Используем API для автоматизации работы с Proxmox Mail Gateway

  • Автор:

pmg-api-000.png Proxmox Mail Gateway - бесплатный, но гибкий и мощный пограничный почтовый шлюз от компании Proxmox, более известной своими средствами виртуализации. Как и остальные продукты, он выделяется простым и удобным веб-интерфейсом, позволяющим быстро и удобно настраивать продукт. Но как быть, если нужно выполнить большое количество однотипных действий? Либо интегрировать шлюз с каким-либо иным используемым вами ПО? В таком случае вам следует использовать API - специальный программный интерфейс, открывающий широкие возможности для автоматизации.

Как и многие другие наши статьи, эта появилась благодаря обратной связи. Один из наших коллег спросил: а можно ли как-то автоматизировать добавление объектов в белый список? Список относительно небольшой - 150-200 email-адресов и десяток-другой доменов. Но забивать его руками - то еще удовольствие, кроме того, списки следует время от времени дополнять и этот процесс тоже хотелось бы автоматизировать.

Здесь мы вплотную подошли к понятию API (application programming interface) - программного интерфейса приложения, это набор высокоуровневых способов взаимодействия с приложением без необходимости вникать во внутреннее устройство продукта. API, как правило, хорошо документированы и остаются постоянными, либо сохраняют обратную совместимость, на всем жизненном цикле ПО. Это позволяет создать инструмент автоматизации единственный раз и не беспокоиться о том, что разработчики что-то серьезно поменяют в его внутреннем устройстве, разве что только расширять возможности, если в API появятся новые функции.

Proxmox Mail Gateway имеет достаточно обширный и развитый API, который полностью описан в документации. На первый взгляд она может показаться довольно сложной, но на самом деле разобраться в ней несложно, даже если вы делаете это в первый раз.

Слева представлено древовидное представление всех доступных через API объектов, а справа показаны доступные с ними действия. Работать с API можно как по протоколу HTTP, так и через интерфейс командной строки, в данной статье мы будем рассматривать именно последний способ.

Вернемся к нашей задаче, раскроем последовательно пункты config - ruledb - who и найдем объект email, справа мы увидим его состав: строковое поле email для хранения почтового адреса и целочисленный ogroup - идентификатор группы объекта. Также нам доступно действие create, т.е. создание объекта.

pmg-api-001.pngЕсли мы перейдем к уже созданному объекту, то увидим, что в его составе появилось еще одно целочисленное поле - id - идентификатор объекта. Чтобы не путаться в дальнейшем давайте уделим идентификаторам несколько минут. Разворачивая в дереве папку who мы увидим вложенную в нее папку {ogroup}, которая уже содержит все нужные нам объекты. Что такое {ogroup}? Это объект-владелец, если мы заглянем в веб-интерфейс, то увидим, что внутри объекта Who уже созданы два списка, черный и белый, каждый из них имеет свой id, который будет являться ogroup для всех нижестоящих объектов, т.е. показывать их принадлежность к тому или иному списку.

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

pmg-api-002.pngА вот если мы захотим удалить какую-либо запись, то нам придется пойти другим путем. Для этого не нужно уточнять тип записи, достаточно знать ее идентификатор и идентификатор группы владельца.

pmg-api-003.pngКак видим - все довольно несложно, если есть желание, то разобраться в структуре и методах работы с API можно довольно быстро. Тем более что примеры использования приведены на каждой странице, нас сейчас интересуют те, которые помечены как CLI, по сути, это готовые команды, все что вам остается сделать, это правильно подставить в них идентификаторы.

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

Чтобы войти в отдельную консоль достаточно запустить pmgsh без параметров, при этом изменится приглашение командной строки:

pmgsh

Теперь можно выполнять команды, давайте посмотрим какие объекты есть внутри Who:

get /config/ruledb/who

В качестве альтернативы можно выполнить, если вы по какой-то причине не хотите переходить в отдельную консоль, следующую команду:

pmgsh get /config/ruledb/who

pmg-api-004.pngВ выводе мы увидим две предустановленные группы: глобальные белый и черный списки, а также их идентификаторы. Отдельно следует обратить внимание на формат вывода - это JSON, это специальный формат обмена данными, который легко читается людьми и широко поддерживается в различном ПО и языках программирования. Проще говоря, если вам нужно передать результат для автоматической обработки дальше, то это не составит особого труда. Ну а для того, кто знает, что такое JSON и как с ним работать - ничего вообще пояснять не нужно.

Узнав из вывода прошлой команды идентификатор белого списка получим его состав:

get /config/ruledb/who/3/objects

pmg-api-005.pngПока в нем находится один единственный адрес, добавленный разработчиками для примера. Еще одна тонкость, для получения состава списка мы использовали objects, потому как для отдельных видов записей, таких как email, domain или ip действие get недоступно, только create. Чтобы не путаться в доступных действиях всегда смотрите документацию, она должна стать вашей настольной книгой при работе с API Proxmox Mail Gateway.

Давайте попробуем что-нибудь создать, например, новый почтовый адрес:

create /config/ruledb/who/3/email --email ivanov@example.com

В данной команде мы указали ogroup - 3, т.е. белый список, затем уточнили, что создаем объект email и через двойной дефис указали добавляемый параметр и его значение. Затем можем снова запросить список объектов белого списка и увидеть, что в него добавлен еще один адрес.

pmg-api-006.pngАналогичным образом мы можем добавить объект другого типа, скажем, домен:

create /config/ruledb/who/3/domain --domain interface31.ru

А теперь заглянем в веб-интерфейс, где увидим в составе белого списка все добавленные нами через API элементы.

pmg-api-007.pngСоздавать объекты мы уже научились, теперь попробуем удалить. Допустим мы хотим удалить адрес добавленый для примера, для этого нам нужно знать его идентификатор и идентификатор группы, все это есть на скриншотах выше: id - 2, ogroup - 3. Располагая данной информацией выполним команду:

delete /config/ruledb/who/3/objects/2

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

pmg-api-008.pngТеперь, когда вы уже немного освоились с API, перейдем к тому, ради чего мы все это затеяли - автоматизации. Хотя, возможно, найдутся и любители консоли, которым будет удобнее выполнять некоторые действия через API, нежели веб-интерфейс. Но у нас стоит простая, но утомительная задача - добавить в белый список некоторое количество записей, немного, всего сотню - другую.

Давайте для примера создадим аналог такого списка. Перейдем в домашнюю директорию и создадим новый файл, в который внесем необходимые нам электронные адреса:

cd ~
nano email.list

В данном примере мы использовали установленный по умолчанию в системе редактор nano, если у вас установлен mc и вам более по душе его редактор, то выполните:

mcedit email.list

pmg-api-009.pngА теперь внесем этот список в Proxmox Mail Gateway и даже сможем обойтись без скриптов, выполнив в одну строку:

while read email ; do pmgsh create /config/ruledb/who/3/email --email "$email" ; done < email.list

Результатом работы данной конструкции будет вывод идентификатора для каждой добавленной записи.

pmg-api-010.pngТо, что мы сделали, может показаться кому-то особой "консольной магией", но на самом деле все просто. Команда while - do - done запускает цикл, который будет работать до тех пор, пока на вход поступают строковые данные, внутри цикла мы обращаемся к API и записываем новый объект email для каждой прочитанной строки. После чего мы воспользовались перенаправлением потоков и передали на вход команде содержимое текстового файла.

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

pmg-api-011.png

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

Помогла статья? Поддержи автора и новые статьи будут выходить чаще:

Поддержи проект!

Или подпишись на наш Телеграм-канал: Подпишись на наш Telegram-канал



Loading Comments