CLI RouterOS (/system resource print и т.п.) удобен руками, но для автоматического опроса десятков устройств нужен структурированный доступ — RouterOS API возвращает готовые пары «ключ-значение», а не текст, который нужно парсить регулярками. В статье — подключение к RouterOS из Python через librouteros, обработка ошибок соединения и типичные ошибки при опросе.
Почему API, а не парсинг CLI
SSH + парсинг вывода print работает, но ломается при любом изменении формата вывода между версиями RouterOS — ширина столбцов, порядок полей, локализация. RouterOS API (TCP, порт 8728 без шифрования или 8729 с TLS — API-SSL) отдаёт те же данные как бинарный протокол с явными именами полей, не зависящий от того, как CLI форматирует таблицу для терминала.
Выбор библиотеки
Для Python есть несколько реализаций протокола RouterOS API; в статье — librouteros (чистый Python, без внешних зависимостей, одна из активно поддерживаемых реализаций на момент написания):
pip install librouteros
Подключение и опрос
import socket
from librouteros import connect
from librouteros.exceptions import TrapError, ConnectionClosed
def fetch_system_resource(host, username, password, port=8728, timeout=5):
"""Подключается к RouterOS API и возвращает /system/resource как dict."""
try:
api = connect(
host=host,
username=username,
password=password,
port=port,
timeout=timeout,
)
except (socket.timeout, ConnectionRefusedError, OSError) as exc:
raise RuntimeError(f"не удалось подключиться к {host}:{port}: {exc}") from exc
try:
resource = tuple(api.path("system", "resource"))
return resource[0] if resource else {}
except TrapError as exc:
# TrapError — RouterOS вернул ошибку на уровне API (неверные права,
# неправильный путь и т.п.), не ошибка соединения
raise RuntimeError(f"RouterOS API вернул ошибку: {exc}") from exc
except ConnectionClosed as exc:
raise RuntimeError(f"соединение с {host} закрыто во время запроса: {exc}") from exc
api.path("system", "resource") соответствует команде /system resource print в CLI — каждый сегмент пути это слово команды, результат — итератор словарей с теми же полями, что показывает CLI (cpu-load, free-memory, uptime и т.д.), но без необходимости парсить текст.
Опрос другого раздела — тем же способом, меняется только путь:
def fetch_interfaces(host, username, password, port=8728, timeout=5):
"""Возвращает список интерфейсов — аналог /interface print."""
api = connect(host=host, username=username, password=password,
port=port, timeout=timeout)
return list(api.path("interface"))
Права пользователя для мониторинга
Пользователь, под которым опрашивается API, не должен иметь прав full — для чтения /system resource, /interface, /routing и т.п. достаточно группы read:
/user group add name=api-monitor policy=read,api,!write,!ftp,!reboot,!policy,!test,!winbox,!password,!web,!sniff,!sensitive,!romon,!rest-api
/user add name=monitor group=api-monitor password=CHANGE_ME
Отдельный read-only пользователь — не формальность: при утечке пароля скрипта мониторинга (лежит в cron/systemd-юните на сервере-сборщике метрик) злоумышленник получает только чтение, не возможность менять конфигурацию устройства.
API без шифрования — только внутри доверенной сети
Порт 8728 (обычный API) передаёт логин и пароль в открытом виде при установлении сессии. Для опроса устройства из той же защищённой внутренней сети/VPN это обычно приемлемо, но через интернет без туннеля — нет: нужен порт 8729 (API-SSL, с TLS) или сам API-трафик должен идти внутри VPN (WireGuard — см. статью про OSPF поверх WireGuard в этой же серии).
import ssl
ctx = ssl.create_default_context()
api = connect(host=host, username=username, password=password,
port=8729, ssl_wrapper=ctx.wrap_socket)
На реальном устройстве нужно учесть, что у RouterOS по умолчанию самоподписанный сертификат на API-SSL — без отключения проверки цепочки подключение не пройдёт: для рабочего кода нужно импортировать сертификат устройства в доверенные, а не отключать проверку вслепую.
Типичные ошибки
- Таймаут вместо явной ошибки. Если порт закрыт firewall-ом (а не просто не слушается), TCP SYN может просто не получить ответа — тогда соединение не завершится ни успехом, ни быстрым
ConnectionRefusedError, а зависнет доtimeout. Явныйtimeout=вconnect()обязателен — без него скрипт мониторинга может зависнуть на недоступном устройстве на неопределённое время. - Общий пользователь
adminдля API и для ручного логина через Winbox. Если одновременно несколько систем мониторинга и администратор используют один и тот же аккаунт — сложно понять, кто и когда что сделал по логам. Отдельный read-only пользователь на каждую систему мониторинга (см. выше) решает это и ограничивает ущерб при утечке. TrapErrorиз-за опечатки в пути.api.path("system", "resourse")(с опечаткой) вернётTrapErrorс сообщением о неизвестной команде — не ошибка соединения, путь в API строится из тех же слов, что и команда CLI, и ошибается так же легко, как опечатка в консоли.
Итог
RouterOS API через librouteros даёт структурированный доступ к данным устройства без парсинга текстового вывода CLI — удобно для систем мониторинга и автоматизации, опрашивающих десятки устройств по расписанию. Основные практические моменты: отдельный read-only пользователь для опроса, явный timeout на подключении, и API-SSL (порт 8729) или VPN-туннель, если опрос идёт не из доверенной внутренней сети. Код выше проверен локально на уровне синтаксиса и обработки ошибки соединения (подключение к закрытому порту 127.0.0.1:8728 корректно перехватывается как ConnectionRefusedError) — реальный опрос RouterOS-устройства не проверялся, нет доступа к живому стенду в этой сессии. Документация: RouterOS API, librouteros.