Инженер — это не профессия, а состояние души

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.

← Все статьи раздела «Программирование»