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

Примечание

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

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

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

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

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

Описание

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

Требования

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

librouteros
Python >= 3.6 (для librouteros)

Параметры

Параметр	Комментарии
add строка	Добавит выбранные аргументы в указанный путь конфигурации RouterOS. Пример `address=1.1.1.1/32 interface=ether1`. Эквивалент в CLI RouterOS `/ip address add address=1.1.1.1/32 interface=ether1`.
ca_path путь добавлено в community.routeros 1.2.0	Файл в формате PEM, содержащий сертификат CA, который будет использоваться для проверки сертификатов. См. также `validate_cert_hostname`. Используется только при `tls=true` и `validate_certs=true`.
cmd строка	Выполнить произвольную команду в указанном пути, после команды можно добавить `.id`. Пример пути `system script` и команды `run .id=*03` эквивалентен в CLI RouterOS `/system script run number=0`. Пример пути `ip address` и команды `print` эквивалентен в CLI RouterOS `/ip address print`.
encoding строка добавлено в community.routeros 2.1.0	Использование указанного кодирования при общении с устройством RouterOS. По умолчанию `ASCII`. Обратите внимание, что `UTF-8` требует librouteros 3.2.1 или новее. По умолчанию: `"ASCII"`
extended_query словарь	Расширенный запрос по указанному пути для выбранных атрибутов запроса из API RouterOS. Расширенный запрос позволяет использовать сопряженные входные данные. Если соответствующей записи нет, будет возвращен пустой список.
attributes список / элементы=строка / обязательно	Список атрибутов для возврата. Каждый атрибут, используемый в `extended_query.where[]` условии, должен быть указан здесь.
where список / элементы=словарь	Позволяет ограничить возвращаемые объекты. Условиям здесь необходимо соответствовать всем. Условию `extended_query.where[].or` необходимо соответствовать хотя бы одному из его условий.
attribute строка	Атрибут для сопоставления. Должен входить в `extended_query.attributes`. Должно быть указано либо `extended_query.where[].or`, либо все `extended_query.where[].attribute`, `extended_query.where[].is`, и `extended_query.where[].value`.
is строка	Оператор для сопоставления. Для равенства используйте `==` или `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 список / элементы=словарь	Список условий, так что хотя бы одному из них должно соответствовать. Должно быть указано либо `extended_query.where[].or`, либо все `extended_query.where[].attribute`, `extended_query.where[].is`, и `extended_query.where[].value`.
attribute строка / обязательно	Атрибут для сопоставления. Должен входить в `extended_query.attributes`.
is строка / обязательно	Оператор для сопоставления. Для равенства используйте `==` или `eq`. Для меньше `<` или `less`. Для больше `>` или `more`. Используйте `in` для проверки, является ли значение частью списка. В этом случае `extended_query.where[].or[].value` должно быть списком. Варианты: `"=="` `"!="` `">"` `"<"` `"in"` `"eq"` `"not"` `"more"` `"less"`
value любой / обязательно	Значение для сравнения. Должно быть списком для `extended_query.where[].or[].is=in`.
value любой	Значение для сравнения. Должно быть списком для `extended_query.where[].is=in`. Должно быть указано либо `extended_query.where[].or`, либо все `extended_query.where[].attribute`, `extended_query.where[].is`, и `extended_query.where[].value`.
force_no_cert логическое добавлено в community.routeros 2.4.0	Установите в `true` для подключения без сертификата, когда `tls=true`. См. также `validate_certs`. Примечание: это принудительно использует анонимные шифры Diffie-Hellman (ADH). Протокол уязвим для атак «человек посередине», потому что ключи, используемые в обмене, не аутентифицированы. Вместо того, чтобы просто подключаться без сертификата, чтобы «заставить работать», ознакомьтесь с `validate_certs` и `ca_path`. Варианты: `false` ← (по умолчанию) `true`
hostname строка / обязательно	Имя хоста RouterOS API.

пароль строка / обязательно	Пароль пользователя RouterOS.
путь строка / обязательно	Основной путь для всех других аргументов. Если другие аргументы не заданы, API вернёт все элементы в выбранном пути. Пример `ip address`. Эквивалент в RouterOS CLI `/ip address print`.
порт целое число	Порт API RouterOS. Если `tls` установлен, порт будет применяться к TLS/SSL соединению. Значения по умолчанию `8728` для HTTP API и `8729` для HTTPS API.
запрос строка	Используйте заданный путь для поиска выбранных атрибутов запроса в RouterOS API. Ключевое слово 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`, где адрес равен 1.1.1.3/32. Пример пути `interface` и запроса `mtu name WHERE mut > 1400` вернёт только интерфейсы `mtu,name`, где MTU больше 1400. Эквивалент в RouterOS CLI `/interface print where mtu > 1400`.
удалить строка	Удаляет конфигурацию/значение из RouterOS по идентификатору ‘.id’. Пример `03` удалит конфигурацию/значение с `id=03` в выбранном пути. Эквивалент в RouterOS CLI `/ip address remove numbers=1`. Обратите внимание, что `number` в RouterOS CLI отличается от `.id`.
таймаут целое число добавлен в community.routeros 2.3.0	Таймаут для запроса. Значение по умолчанию: `10`
tls псевдонимы: ssl булево	Если установлено, TLS будет использоваться для подключения к API RouterOS. Варианты: `false` ← (по умолчанию) `true`
обновить строка	Обновляет конфигурацию/значение в RouterOS по идентификатору ‘.id’ в выбранном пути. Пример `.id=03 address=1.1.1.3/32` и путь `ip address` заменят существующий IP-адрес на `.id=03`. Эквивалент в RouterOS CLI `/ip address set address=1.1.1.3/32 numbers=1`. Обратите внимание, что `number` в RouterOS CLI отличается от `.id`.
имя_пользователя строка / обязательно	Логин пользователя RouterOS.
проверка_имени_хоста_сертификата булево добавлен в community.routeros 1.2.0	Установите в `true` для проверки имён хостов в сертификатах. См. также `validate_certs`. Используется только при `tls=true` и `validate_certs=true`. Варианты: `false` ← (по умолчанию) `true`
проверка_сертификатов булево добавлен в community.routeros 1.2.0	Установите в `false` чтобы пропустить проверку TLS сертификатов. См. также `validate_cert_hostname`. Используется только при `tls=true`. Примечание: вместо простого отключения проверки сертификатов, чтобы «заставить работать», рассмотрите возможность создания собственного сертификата CA и использования его для подписи сертификатов, используемых для вашего маршрутизатора. Вы можете сообщить модулю о своём сертификате CA с помощью опции `ca_path`. Варианты: `false` `true` ← (по умолчанию)

Атрибуты

Атрибут	Поддержка	Описание
группа_действий	Группа действий: community.routeros.api добавлен в community.routeros 2.1.0	Используйте `group/community.routeros.api` в `module_defaults` для установки значений по умолчанию для данного модуля.
режим_проверки	Поддержка: нет	Может работать в режиме `check_mode` и возвращать прогноз изменения статуса без изменения целевого объекта.
режим_сравнения	Поддержка: нет	Вернёт детали изменений (или, возможно, требующих изменения в `check_mode`) в режиме сравнения.
платформа	Платформа: 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 список / элементы=строка	Все выводы находятся в списке со словарями, возвращаемыми API RouterOS. Возвращается: всегда Пример: `[{"address": "1.2.3.4"}, {"address": "2.3.4.5"}]`

Авторы

Николай Дачев (@NikolayDachev)

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

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