Модуль community.routeros.api — модуль Ansible для API RouterOS

Примечание

Этот модуль входит в коллекцию community.routeros (версия 3.20.0).

Возможно, эта коллекция уже установлена, если вы используете пакет ansible. Она не включена в ansible-core. Чтобы проверить, установлена ли она, выполните ansible-galaxy collection list.

Чтобы установить её, используйте: ansible-galaxy collection install community.routeros. Для использования этого модуля требуются дополнительные компоненты; подробности см. в разделе Требования.

Чтобы использовать его в плейбуке, укажите: community.routeros.api.

Краткое описание
Требования
Параметры
Атрибуты
Примечания
См. также
Примеры
Возвращаемые значения

Краткое описание

Модуль Ansible для API RouterOS с библиотекой Python librouteros.
Этот модуль позволяет добавлять, удалять, обновлять, запрашивать и выполнять произвольные команды в RouterOS через API.

Требования

На хосте, выполняющем этот модуль, должны быть установлены следующие компоненты.

librouteros
Python >= 3.6 (для librouteros)

Параметры

Параметр	Комментарии
add string	Добавляет выбранные аргументы в выбранный путь конфигурации RouterOS. Пример `address=1.1.1.1/32 interface=ether1`. Эквивалент в CLI RouterOS: `/ip address add address=1.1.1.1/32 interface=ether1`.
ca_path path добавлено в community.routeros 1.2.0	Файл в формате PEM, содержащий сертификат центра сертификации (CA), который будет использоваться для проверки сертификатов. См. также `validate_cert_hostname`. Используется только при `tls=true` и `validate_certs=true`.
cmd string	Выполняет любую/произвольную команду в выбранном пути; после команды можно добавить `.id`. Путь `system script` и команда `run .id=*03` эквивалентны в CLI RouterOS команде `/system script run number=0`. Путь `ip address` и команда `print` эквивалентны в CLI RouterOS команде `/ip address print`.
encoding string добавлено в community.routeros 2.1.0	Использовать указанную кодировку при взаимодействии с устройством RouterOS. По умолчанию используется `ASCII`. Обратите внимание: для `UTF-8` требуется librouteros версии 3.2.1 или новее. По умолчанию: `"ASCII"`
extended_query dictionary	Расширенный запрос к указанному пути для выбранных атрибутов запроса из API RouterOS. Расширенный запрос позволяет задавать условия совместно. Если совпадений нет, будет возвращён пустой список.
attributes list / elements=string / обязательный	Список атрибутов, которые нужно вернуть. Каждый атрибут, используемый в условии `extended_query.where[]`, должен быть указан здесь.
where list / elements=dictionary	Позволяет ограничить возвращаемые объекты. Все указанные здесь условия должны выполняться. В условии `extended_query.where[].or` достаточно выполнения хотя бы одного из входящих в него условий.
attribute string	Атрибут для сопоставления. Должен входить в `extended_query.attributes`. Необходимо указать либо `extended_query.where[].or`, либо все параметры `extended_query.where[].attribute`, `extended_query.where[].is` и `extended_query.where[].value`.
is string	Оператор, используемый для сопоставления. Для проверки равенства используйте `==` или `eq`. Для проверки меньшего значения используйте `<` или `less`. Для проверки большего значения используйте `>` или `more`. Используйте `in`, чтобы проверить, входит ли значение в список. В этом случае `extended_query.where[].value` должен быть списком. Необходимо указать либо `extended_query.where[].or`, либо все параметры `extended_query.where[].attribute`, `extended_query.where[].is` и `extended_query.where[].value`. Допустимые значения: `"=="` `"!="` `">"` `"<"` `"in"` `"eq"` `"not"` `"more"` `"less"`
or list / elements=dictionary	Список условий, из которых должно выполняться хотя бы одно. Необходимо указать либо `extended_query.where[].or`, либо все параметры `extended_query.where[].attribute`, `extended_query.where[].is` и `extended_query.where[].value`.
attribute string / обязательный	Атрибут для сопоставления. Должен входить в `extended_query.attributes`.
is string / обязательный	Оператор, используемый для сопоставления. Для проверки равенства используйте `==` или `eq`. Для проверки меньшего значения используйте `<` или `less`. Для проверки большего значения используйте `>` или `more`. Используйте `in`, чтобы проверить, входит ли значение в список. В этом случае `extended_query.where[].or[].value` должен быть списком. Допустимые значения: `"=="` `"!="` `">"` `"<"` `"in"` `"eq"` `"not"` `"more"` `"less"`
value any / обязательный	Значение для сравнения. Для `extended_query.where[].or[].is=in` должно быть списком.
value any	Значение для сравнения. Для `extended_query.where[].is=in` должно быть списком. Необходимо указать либо `extended_query.where[].or`, либо все параметры `extended_query.where[].attribute`, `extended_query.where[].is` и `extended_query.where[].value`.
force_no_cert boolean добавлено в community.routeros 2.4.0	Установите значение `true`, чтобы подключаться без сертификата при `tls=true`. См. также `validate_certs`. Примечание: это принудительно включает шифры анонимного Диффи — Хеллмана (ADH). Протокол уязвим для атак «человек посередине», поскольку ключи, используемые при обмене, не проходят аутентификацию. Вместо того чтобы просто подключаться без сертификата, чтобы «заставить всё работать», ознакомьтесь с `validate_certs` и `ca_path`. Допустимые значения: `false` ← (по умолчанию) `true`
hostname string / обязательный	Имя хоста RouterOS API.
password string / обязательный	Пароль пользователя RouterOS.
path string / обязательный	Основной путь для всех остальных аргументов. Если другие аргументы не заданы, модуль вернёт все элементы выбранного пути. Пример `ip address`. Эквивалент команды CLI RouterOS `/ip address print`.
port integer	Порт RouterOS API. Если задано `tls`, порт будет использоваться для TLS/SSL-соединения. Порты по умолчанию: `8728` для HTTP API и `8729` для HTTPS API.
query string	Запрос к указанному пути для выбранных атрибутов запроса из API RouterOS. WHERE — ключевое слово, расширяющее запрос. Формат WHERE: ключ оператор значение, разделённые пробелами. Допустимые операторы WHERE: `==` или `eq`, `!=` или `not`, `>` или `more`, `<` или `less`. Пример: путь `ip address` и запрос `.id address` вернут только `.id` и `address` для всех элементов пути `ip address`. Пример: путь `ip address` и запрос `.id address WHERE address == 1.1.1.3/32` вернут только `.id` и `address` для элементов пути `ip address`, у которых address равен 1.1.1.3/32. Пример: путь `interface` и запрос `mtu name WHERE mut > 1400` вернут только интерфейсы `mtu,name`, у которых mtu больше 1400. Эквивалент в CLI RouterOS: `/interface print where mtu > 1400`.
remove string	Удаляет конфигурацию/значение из RouterOS по «.id». Пример `03` удалит конфигурацию/значение с `id=03` в выбранном пути. Эквивалент в CLI RouterOS: `/ip address remove numbers=1`. Обратите внимание: `number` в CLI RouterOS отличается от `.id`.
timeout integer добавлено в community.routeros 2.3.0	Тайм-аут запроса. По умолчанию: `10`
tls псевдонимы: ssl boolean	Если параметр включён, для подключения к RouterOS API будет использоваться TLS. Допустимые значения: `false` ← (по умолчанию) `true`
update string	Обновляет конфигурацию/значение в RouterOS по «.id» в выбранном пути. Пример `.id=03 address=1.1.1.3/32` и путь `ip address` заменят существующий IP-адрес на `.id=03`. Эквивалент в CLI RouterOS: `/ip address set address=1.1.1.3/32 numbers=1`. Обратите внимание: `number` в CLI RouterOS отличается от `.id`.
username string / обязательный	Имя пользователя для входа в RouterOS.
validate_cert_hostname boolean добавлено в community.routeros 1.2.0	Установите значение `true`, чтобы проверять имена хостов в сертификатах. См. также `validate_certs`. Используется только при `tls=true` и `validate_certs=true`. Допустимые значения: `false` ← (по умолчанию) `true`
validate_certs boolean добавлено в community.routeros 1.2.0	Установите значение `false`, чтобы отключить проверку TLS-сертификатов. См. также `validate_cert_hostname`. Используется только при `tls=true`. Примечание: вместо того чтобы просто отключать проверку сертификатов, чтобы «заставить всё работать», рассмотрите возможность создания собственного сертификата CA и его использования для подписи сертификатов вашего маршрутизатора. Сообщить модулю о сертификате CA можно с помощью параметра `ca_path`. Допустимые значения: `false` `true` ← (по умолчанию)

Атрибуты

Атрибут	Поддержка	Описание
action_group	Группа действий: community.routeros.api добавлено в community.routeros 2.1.0	Используйте `group/community.routeros.api` в `module_defaults`, чтобы задать значения по умолчанию для этого модуля.
check_mode	Поддержка: нет	Может выполняться в режиме `check_mode` и возвращать прогноз изменения состояния без изменения целевого объекта.
diff_mode	Поддержка: нет	В режиме сравнения возвращает сведения об изменениях (или о том, что, возможно, потребуется изменить в `check_mode`).
idempotent	Поддержка: не применимо Идемпотентность выполненной команды зависит от выполняемой операции.	При повторном запуске с теми же аргументами вне режима проверки второй вызов сообщает об отсутствии изменений. Предполагается, что система, которой управляет модуль или к которой он обращается, не изменилась существенным образом.
platform	Платформа: RouterOS	Целевая ОС/семейства ОС, с которыми можно работать.

Примечания

Примечание

add, remove, update, cmd и query являются взаимоисключающими.
Для более точечного изменения используйте модули community.routeros.api_modify и community.routeros.api_find_and_modify, а для более контролируемого возврата всех записей указанного пути — модуль community.routeros.api_info.

См. также

Как заключать команды и аргументы в кавычки и удалять кавычки: Как заключать команды и аргументы в кавычки и удалять кавычки.
community.routeros.api_facts: Сбор фактов с удалённых устройств под управлением MikroTik RouterOS с помощью API.
community.routeros.api_find_and_modify: Поиск и изменение данных с помощью API.
community.routeros.api_info: Получение информации через API.
community.routeros.api_modify: Изменение данных по путям с помощью API.
Как подключаться к устройствам RouterOS с помощью API RouterOS: Как подключаться к устройствам RouterOS с помощью API RouterOS.

Примеры

---
- name: Get example - ip address print
  community.routeros.api:
    hostname: "{{ hostname }}"
    password: "{{ password }}"
    username: "{{ username }}"
    path: "ip address"
  register: ipaddrd_printout

- name: Dump "Get example" output
  ansible.builtin.debug:
    msg: '{{ ipaddrd_printout }}'

- name: Add example - ip address
  community.routeros.api:
    hostname: "{{ hostname }}"
    password: "{{ password }}"
    username: "{{ username }}"
    path: "ip address"
    add: "address=192.168.255.10/24 interface=ether2"

- name: Query example - ".id, address" in "ip address WHERE address == 192.168.255.10/24"
  community.routeros.api:
    hostname: "{{ hostname }}"
    password: "{{ password }}"
    username: "{{ username }}"
    path: "ip address"
    query: ".id address WHERE address == {{ ip2 }}"
  register: queryout

- name: Dump "Query example" output
  ansible.builtin.debug:
    msg: '{{ queryout }}'

- name: Extended query example - ".id,address,network" where address is not 192.168.255.10/24 or is 10.20.36.20/24
  community.routeros.api:
    hostname: "{{ hostname }}"
    password: "{{ password }}"
    username: "{{ username }}"
    path: "ip address"
    extended_query:
      attributes:
        - network
        - address
        - .id
      where:
        - attribute: "network"
          is: "=="
          value: "192.168.255.0"
        - or:
            - attribute: "address"
              is: "!="
              value: "192.168.255.10/24"
            - attribute: "address"
              is: "eq"
              value: "10.20.36.20/24"
        - attribute: "network"
          is: "in"
          value:
            - "10.20.36.0"
            - "192.168.255.0"
  register: extended_queryout

- name: Dump "Extended query example" output
  ansible.builtin.debug:
    msg: '{{ extended_queryout }}'

- name: Update example - ether2 ip address with ".id = *14"
  community.routeros.api:
    hostname: "{{ hostname }}"
    password: "{{ password }}"
    username: "{{ username }}"
    path: "ip address"
    update: >-
      .id=*14
      address=192.168.255.20/24
      comment={{ 'Update 192.168.255.10/24 to 192.168.255.20/24 on ether2' | community.routeros.quote_argument_value }}

- name: Remove example - ether2 ip 192.168.255.20/24 with ".id = *14"
  community.routeros.api:
    hostname: "{{ hostname }}"
    password: "{{ password }}"
    username: "{{ username }}"
    path: "ip address"
    remove: "*14"

- name: Arbitrary command example "/system identity print"
  community.routeros.api:
    hostname: "{{ hostname }}"
    password: "{{ password }}"
    username: "{{ username }}"
    path: "system identity"
    cmd: "print"
  register: arbitraryout

- name: Dump "Arbitrary command example" output
  ansible.builtin.debug:
    msg: '{{ arbitraryout }}'

Возвращаемые значения

Общие возвращаемые значения описаны здесь; ниже перечислены поля, уникальные для этого модуля:

Ключ	Описание
message list / elements=string	Все выходные данные представлены в виде списка со словарями, возвращёнными API RouterOS. Возвращается: всегда Пример: `[{"address": "1.2.3.4"}, {"address": "2.3.4.5"}]`

Авторы

Nikolay Dachev (@NikolayDachev)

Ссылки на коллекцию

© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/projects/ansible/latest/collections/community/routeros/api_module.html