Управление интернет-реле из RouterOS Mikrotik через API

Удобный инструмент для управления PDU в роутерах MikroTik

Компания MikroTik известна как производитель сетевого оборудования, отличающегося высокой надежностью при низкой цене и богатой функциональности. Программной основой для продуктов MikroTik является RouterOS – сетевая операционная система на базе Linux. Она запускается на RouterBOARD – большой линейке аппаратных решений, которая включает в себя как чисто операторское оборудование, так и платформы для домашнего использования. RouterOS предоставляет администратору/пользователю большие возможности настройки и управления маршрутизатором, позволяя оперировать не только встроенным функционалом системы, но и создавать свои варианты практически любых решений, через скрипт-программирование.

В данной статье я рассмотрю как можно использовать расширенный функционал роутеров MikroTik для подачи команд управления электропитанием при помощи PDU (интернет-реле) непосредственно с роутера через функции-скрипты. В качестве PDU я использовал Ethernet-реле RODOS-8/9/10 фирмы «ОЛИМП» (устройства абсолютно идентичны в плане управления), которые остались после нескольких проектов и были «под рукой».

Возможности RouterOS для управления PDU

Расширенный функционал RouterOS может позволить:

• Удаленно включать/выключать питание подключенных к PDU устройств
• Удаленно управлять PDU по наступлению различных событий в сети (скажем, при отсутствии ответа от какого-либо устройства на ping, при подключении к роутеру определенного VPN-клиента, клиента wifi-сети и.т.д…), в зависимости от времени (по расписанию)
• Производить оповещение администратора или пользователей об изменении состояния реле на PDU на электронную почту или номер телефона (по SMS)

Таким образом, можно организовать, например, управление оборудованием серверной, включать/выключать/перезагружать «зависшее» сетевое оборудование, включать охлаждение или обогрев, освещение, управлять любыми допустимыми по номинальной мощности нагрузками в составе «Умного дома» и многое другое, что сможет позволить Ваше воображение.

Возможность управлять интернет-реле из RouterOS предоставляет команда роутера fetch, синтаксис которой подробно описан по ссылке в конце статьи.

Управление PDU через команду роутера «fetch»

PDU RODOS-8/9/10 поддерживают следующий формат URL-обращений:

Таким образом, для решения нашей задачи в RouterOS, чтобы включить первое реле нашего PDU, достаточно следующей записи:

/tool fetch url="http://[логин:пароль]@192.168.1.20/protect/rb0n"

Если мы хотим, чтобы от устройства вернулся ответ, следует использовать:

/tool fetch url="http://[логин:пароль]@192.168.1.20/protect/rb0n" mode=http dst-path="Rodosanswer.txt"; :local Rodosanswer [/file get Rodosanswer.txt contents];

Ответ PDU в нашем случае возвращается с помощью механизма json в переменную Rodosanswer в следующем виде:

• «Success! » – в случае успешного выполнения команды
• «Fault» – при невыполнении команды (как правило, при обращении без указания в URL-строке логина и пароля PDU, если PDU находится в «защищенном» режиме)

Создаем функцию управления PDU Rodos в репозитории роутера Мikrotik

Итак, приступим. Создадим функцию управлением реле на примере управления RODOS-10 в реппозитории скриптов роутера MikroTik под именем «Func_RODOS10rele»:

################ FuncRODOS10rele ###################### # Функция установки состояния реле PDU RODOS-10 #         by Sergej Serkov 23.12.2017 #######################################################  # определяем функцию, устанавливающую реле  :global FuncRODOS10rele do={      :local Sport "";      :if ([:len $Rport]=0) do={:set Sport "80";} else={:set Sport $Rport;}      :global FuncPing; :local PingAnswer [$FuncPing PingAdr=$Radr];          :if ($PingAnswer="OK") do={          :local Rprotect; :local Wprotect; :local Rmode "0"; :local Nrele 0; :local Act;          :if (([:len $Rlogin]=0) and ([:len $Rpass]=0)) do={:set Rprotect ""; set Wprotect "";} else={:set Rprotect ("$Rlogin".":"."$Rpass"."@"); set Wprotect "/protect";}          :if ($Rstatus="on") do={:set Rmode "1"; :set Act "n"}          :if ($Rstatus="off") do={:set Rmode "1"; :set Act "f"}          :if ($Rstatus="inv") do={:set Rmode "1"; :set Act "s"} else={}    :if ($Rmode="1") do={             :set Nrele ([:tonum $Rrele] - 1);             :if (($Nrele > -1 and ($Nrele < 4)) do={             :local StrFetchRodos; :set StrFetchRodos ("http://"."$Rprotect"."$Radr".":"."$Sport"."$Wprotect"."/rb"."$Nrele"."$Act".".cgi");               do { [/tool fetch url=$StrFetchRodos mode=http dst-path="Rodosanswer.txt";];                     } on-error={: log info ""; :log error ("Call ERROR function  ERROR fetch command");                        :local Rodosanswer "ERROR: command ROS "; : log info ""; :return $Rodosanswer}                  :log info "";                  :log warning ("Сall "."$Wprotect "."function  set rele #"."$Rrele "."is ["."$Rstatus"."]");                  :log info "";                  :delay 2s;                  :local Rodosanswer [/file get Rodosanswer.txt contents];                   /file remove Rodosanswer.txt;                  :return $Rodosanswer;                } else={ :log info ""; :log error ("Сall ERROR"."$Wprotect "."function  set rele#"."$Rrele"." but NUMBER RELE MISMATCH"); :log info "";                :local Rodosanswer "ERROR: rele range mismath"; :return $Rodosanswer;}        } else={ :log info ""; :log error ("Сall ERROR"."$Wprotect "."function  set rele#"."$Rrele"." but RELE REGIME SET MISMATCH"); :log info "";               :local Rodosanswer "ERROR: rele regime set mismatch"; :return $Rodosanswer;}     } else={ :log info ""; :log error ("Сall ERROR"."$Wprotect "."function  but DEVICE NOT RESPONDED"); :log info "";        :local Rodosanswer "ERROR: device not responded"; :return $Rodosanswer;} } 

Функция FuncRODOS10rele также использует в своей работе другую небольшую функцию проверки сетевого адреса на ping – FuncPing, которая должна присутствовать в окружении переменных реппозитория роутера при работе основной функции.

:global FuncPing do={ :local PingCount 3; # количество пингов; :local Result [/ping $PingAdr count=$PingCount]; :delay 2s; :local PingAnswer ""; :local MainIfInetOk false; :set MainIfInetOk ((3*$Result) >= (2 * $PingCount)) :put "MainIfInetOk=$MainIfInetOk" if (!$MainIfInetOk) do={ :set PingAnswer "ERROR" } if ($MainIfInetOk) do={ :set PingAnswer "OK" } :return $PingAnswer;} 

Применение функции управления реле

В качестве параметров функции FuncRODOS10rele нужно передавать следующее:

• Radr – IP-адрес устройства
• Rport — http порт. Если настроен стандартный порт для http (80) этот параметр можно не указывать
• Rrele — номер реле над которым производим действие (для RODOS-10 [1-4]),
  для RODOS-9 [1-2], для RODOS-8 не передается)
• Rstatus — совершаемое действие («off»-выключить; «on»-включить; «inv» — выдать импульс)
• Rlogin — логин, Rpass — пароль доступа к устройству
  (eсли они не заданы используется вызов команды без «/protect»)

[$FuncRODOS10rele Radr="192.168.1.20" Rrele="2" Rstatus="on"]

[$FuncRODOS10rele Radr="192.168.1.20" Rport="8021" Rrele="2" Rstatus="off" Rlogin="login" Rpass="password"]

Ответ функции может быть возвращен в строковую переменную Rodosanswer.

  • "Success! " - в случае успешного обращения и исполнения команды   • "Fault" - в случае ошибочного обращения и неисполнения команды   • "ERROR: rele range mismatch" - в случае указания недопустимого номера реле  	в параметре функции Rrele для данной версии устройства   • "ERROR: rele regime set mismatch" - в случае незаданного либо неверно      заданного параметра функции Rstatus ("on", "off", "inv")   • "ERROR: device not responded" - в случае отсутствия ответа от устройства      на пинг   • "ERROR: command ROS " - в случае возникновения ошибки непосредственно     при исполнении URL-команды RouterOS fetch (как правило, при неправильно     указанном номере порта в Rport, неправильно указанных параметрах Rlogine     и/или Rpass) 

Вызывать функцию управления реле на PDU можно из любых других Ваших скриптов следующим образом:

1. Сначала нужно исполнить скрипты, размещающие нужные функции в окружении переменных реппозитория роутера. Это можно сделать однократно, например, при старте роутера из Планировщика RouterOS (/system sсheduler)

   # однократно запускаем скрипт функции для ее размещения в окружении /system script run Func_RODOS10rele;   # аналогично устанавливаем в окружение функцию «FuncPing»  # (используется функцией FuncRODOS10rele) /system script run Func_Ping; 

2. После того, как функции определены, можно ими пользоваться (в частности вызывать FuncRODOS10rele)

   В качестве примера вызовем нашу функцию, подав импульс на реле №4 PDU RODOS-10:

   :global FuncRODOS10rele; :local Rodosanswer [$FuncRODOS10rele Radr="192.168.1.20" Rport="8021" Rrele="4" Rstatus="inv" Rlogin="login" Rpass="password"]; :log info $Rodosanswer; 

   Ответ будет возвращен в переменную Rodosanswer и, в данном случае, отображен в логе роутера.

   Готовая библиотека функций для работы с PDU

   Для удобства использования мной была создана библиотека функций для PDU Rodos моделей 8, 9, 10 и 10 исполнения DIN (версия библиотеки 1.0 от 25 декабря 2017 г). Скрипты библиотеки объединены в файл Func_RODOS.rsc, который может быть импортирован в RouterOS следующей командой терминала утилиты WINBOX:

   /import file= Func_RODOS.rsc

   Процесс импорта может занять от 20 секунд до 1 минуты в зависимости от модели роутера Микротик (его быстродействия).
   При этом все скрипты, ранее имевшиеся в роутере не затрагиваются, функции и скрипты библиотеки Func_RODOS добавляются к существующим скриптам реппозитория.

   Библиотека Rodos.rsc версии 1.0 содержит следующие скрипты:

   • start_RODOS – запуск этого скрипта устанавливает все функции в Окружение переменных
   • Func_Ping – функция проверки адреса на «пинг»
   • Func_Mail – функция отправки произвольного сообщения на почту администратора роутера
   • Func_RODOS8rele – функция управления реле PDU RODOS-8
   • Func_RODOS8reset – функция сброса («перезагрузки») реле PDU RODOS-8
   • Func_RODOS9rele — … аналогично для указанных моделей …
   • Func_RODOS9reset
   • Func_RODOS10rele
   • Func_RODOS10reset
   • call_example […] – примеры вызовов функций библиотеки
   • Func_RODOS_lib – все функции PDU (кроме Ping и Maйл) в одном файле-скрипте

   После импорта библиотеки Вы можете удалить ненужные функции и скрипты из реппозитория, оставив только функции своей модели PDU и скрипты с функциями FuncMail и FuncPing.

   В библиотеке, для каждой из поддерживаемых моделей PDU, также присутствуют удобные функции сброса («перезагрузки») (помечены в названиях как «~reset»). Параметры функций перезагрузки аналогичны параметрам функций установки реле, за исключением параметра «Rstatus», который не используется при «перезагрузке» и введенного дополнительного необязательного параметра Rtime, определяющего время в секундах между выключением и включением переключаемого реле (если Rtime не передается функции, по умолчанию используется время 5 секунд).

   Функции перезагрузки работают следующим образом:

   1. Указанному реле отправляется команда на выключение
   2. Затем производится ожидание Rtime секунд с последующей командой включения. При этом функции перезагрузки обращаются к соответствующим функциям установки реле, которые должны быть определены до вызова первых

   Таким образом, если до вызова функции перезагрузки, определенное реле было включено, оно будет выключено и через заданное время снова включено (а нагрузка, подключенная к нему, «перезагружена»). Над выключенным реле производится аналогичная операция и после работы функции реле становится включенным (то есть, в этом случае функция отрабатывает как функция включения реле). Функции сброса удобно использовать для перезагрузки, подключенного к PDU Rodos «зависшего» сетевого оборудования (точек доступа, роутеров, свичей, различных серверов и т.д…).

   Исходные коды библиотеки Rodos.rsc (функции и скрипты-примеры обращения к ним) достаточно подробно «прокомментированы», что может пригодиться желающим детально разобраться в работе библиотеки (а возможно и самостоятельно доработать их, либо написать свой вариант).

   В примерах вызовов функций перезагрузки после отработки действия функции реализована отправка сообщений на адрес электронной почты администратора роутера (в настройках переменных скрипта Вы можете указать свой почтовый адрес). При этом скриптами используется почтовая служба RouterOS из /tool e-mail, параметры которой должны быть Вами заранее корректно настроены.

   Планы на будущее

   В последующем библиотека скриптов для PDU Rodos будет расширяться — планируется создание функций для интернет-метеостанции RODOS-16, имеющей «на борту», помимо реле, линии ввода/вывода и датчики температуры / влажности / атмосферного давления. Также планируется реализовать логирование работы функций не только в лог роутера и на почту, но и на заданный номер телефона по выбору пользователя (посредством отправки SMS-сообщений через модем роутера).

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

   Ссылка на описание команды Fetch для роутеров MikroTik
   Ссылка на документацию к используемым PDU
   Ссылка на библиотеку скриптов-функций для PDU Rodos

   Серков Сергей Владимирович, 26.12.2017 г.