Содержание

Введение

Примечания и предупреждения

Примечания содержат важную информацию, советы или рекомендации по использованию и настройке устройства.

Предупреждения информируют пользователя о ситуациях, которые могут нанести вред программно-аппаратному комплексу, привести к некорректной работе системы или потере данных.

Коллекция Ansible для маршрутизаторов ESR включает в себя модули, позволяющие автоматизировать управление сетевыми устройствами Eltex ESR.

Для получения информации об использовании Ansible для управлении сетевыми устройствами обратитесь к официальному руководству Ansible

Модули

esr_config - модуль для конфигурирования устройств;

esr_command - модуль для отправки команд на устройства.

В следующих главах будет представлено более детальное описание этих модулей.

Установка коллекции

Желательно производить установку коллекции и зависимостей для нее в отдельной виртуальной среде (venv).

Для корректной работы модулей требуется версия python >= 3.11

Ссылка на PlayBook:

ansible.zip

Установка зависимостей:
(venv)user@user:~/eltex/esr/ansible-playbooks$ pip install -r requirements.txt 

Установка коллекции:
(venv)user@user:~/eltex/esr/ansible-playbooks$ cd eltex.esr
(venv)user@user:~/eltex/esr/ansible-playbooks/eltex.esr$ ansible-galaxy collection build --force .
Created collection for eltex.esr at /home/user/eltex/esr/ansible-playbooks/eltex.esr/eltex-esr-2.1.0.tar.gz
(venv)user@user:~/eltex/esr/ansible-playbooks/eltex.esr$ ansible-galaxy collection install --force eltex-esr-2.1.0.tar.gz

После установки удаляем артефакты:
(venv)user@user:~/eltex/esr/ansible-playbooks/eltex.esr$ rm eltex-esr-2.1.0.tar.gz

Модуль esr_command

Данный модуль отправляет произвольные команды на маршрутизатор ESR и возвращает результаты, полученные с устройства.

Параметры

Параметр	Варианты/По умолчанию	Комментарий
commands - / required		Список команд для отправки на удалённый маршрутизатор ESR. Возвращается вывод команд. Если отправляемая команда ожидает ответа на вопрос, то возможно отправить словарь, содержащий command, answer и prompt. Обычные ответы: 'y', 'n'. Смотрите примеры.
interval	По умолчанию: 1	Данный параметр определяет интервал в секундах для ожидания между повторными попытками выполнения команды. Если вывод команды не удовлетворяет заданным условиям, интервал указывает время ожидания перед повторной отправкой команды.
match	Варианты: any all ←	Данный параметр используется вместе с параметром wait_for для указания политики соответствия. Допустимые значения - all или any. Если установлено значение all, то все условия в wait_for должны быть выполнены. Если установлено значение any, то выполнится должно только одно из условий.
retries	По умолчанию: 10	Количество попыток отправки команд, прежде чем она будет считаться неудачной. Команда запускается на удалённом устройстве при каждой попытке и её вывод сравнивается с условиями wait_for.
wait_for		Список условий для сравнения с выводом команды. Задача будет ожидать выполнения каждого условия, прежде чем продолжить. Если вывод команды не соответствует условиям в течение настроенного числа попыток, то задача завершится с ошибкой. Смотрите примеры.

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

В общем случае возвращаемые значения описаны здесь. Ниже перечислены уникальные для модуля значения:

Значение

Описание

stdout

list

Набор ответов, полученных с устройства после выполнение команд

Пример:

['...', '...']

stdout_lines

list

Значение stdout в виде списка

Пример:

[['...', '...'], ['...'], ['...']]

Примеры использования модуля в плейбуках

- name: set_inactive_image_task
  esr_command:
    commands:
      - command: "boot system inactive"
        prompt: Continue?
        answer: y
    wait_for: result[0] contains successfully

- name: show_task
  esr_command:
    commands: "{{ esr_commands | default('') | split('\\n') }}"

Пример запуска плейбука с модулем esr_command

Плейбук show_version:

- name: show_version
  tags: show_version
  hosts: all
  connection: network_cli
  vars:
    ansible_network_os: eltex.esr.esr
    esr_commands: show version
  collections:
    - eltex.esr
  gather_facts: False
  tasks:
    - name: show version data
      include_tasks: base_tasks/commands_task.yml

Задача commands_tasks:

- name: show_task
  esr_command:
    commands: "{{ esr_commands | default('') | split('\\n') }}"

Запуск плейбука:

(venv)user@user:~/eltex/esr/ansible-playbooks$ ansible-playbook -i hosts.ini playbooks/show_version.yml -vvv

Результат выполнения плейбука:

PLAYBOOK: show_version.yml *************************************************************************************************************************************************************************************************************
1 plays in playbooks/show_version.yml

PLAY [show_version] ********************************************************************************************************************************************************************************************************************

TASK [show version data] ***************************************************************************************************************************************************************************************************************
task path: /home/user/eltex/esr/ansible-playbooks/playbooks/show_version.yml:12
included: /home/user/eltex/esr/ansible-playbooks/playbooks/base_tasks/commands_task.yml for 192.168.35.213

TASK [show_task] ***********************************************************************************************************************************************************************************************************************
task path: /home/user/eltex/esr/ansible-playbooks/playbooks/base_tasks/commands_task.yml:1

ok: [192.168.35.213] => {
    "changed": false,
    "invocation": {
        "module_args": {
            "commands": [
                "show version"
            ],
            "interval": 1,
            "match": "all",
            "provider": null,
            "retries": 10,
            "wait_for": null
        }
    },
    "stdout": [
        "Boot version:\n  1.28.0.5 (2025-02-04 15:40:11)\nSW version:\n  1.28.0 build 5[edb36bd5db] (2025-02-04 15:35:33)\nHW version:\n  1v1"
    ],
    "stdout_lines": [
        [
            "Boot version:",
            "  1.28.0.5 (2025-02-04 15:40:11)",
            "SW version:",
            "  1.28.0 build 5[edb36bd5db] (2025-02-04 15:35:33)",
            "HW version:",
            "  1v1"
        ]
    ]
}

PLAY RECAP *****************************************************************************************************************************************************************************************************************************
192.168.35.213             : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

Модуль esr_config

Описание

Данный модуль позволяет управлять как отдельными частями конфигурации, так и загружать файл конфигурации целиком.

Параметры

Параметр	Варианты/По умолчанию	Комментарий
after -		Упорядоченный набор команд, которые необходимо выполнить на устройстве после выполнения команд в списке lines. Данные команды будут выполнены только если должны быть внесены изменения, при этом они будут выполнены в независимости от того, есть ли они в текущей конфигурации.
apply_when -	Варианты: always modified ← never	Данный параметр управляет отправкой команды commit на устройство. Если параметр установлен в always, то команда commit отправится на устройство в независимости от необходимости внесения изменений. Если параметр установлен в modified, то команда commit отправится на устройство только в том случае, если текущая конфигурация устройства отличается от исходной. Если параметр установлен в never, то команда commit не будет отправлена на устройство. Если команда commit была отправлена на устройство, то будет активирован таймер (по умолчанию 600 секунд), по истечению которого на устройстве будет произведён автоматический откат на действующую ранее конфигурацию. Для остановки этого таймера и применения внесённых изменений необходимо использовать параметр save_when.
backup boolean	Варианты: True False ←	Данный параметр даёт указание модулю получить полный бэкап текущей конфигурации с устройства, прежде чем какие-либо изменения будут произведены. Файл бэкапа будет сохранён в каталоге backup в корневой директории плейбука. Если каталог отсутствует, то он будет создан.
before -		Упорядоченный набор команд, которые необходимо выполнить на устройстве до выполнения команд в списке lines. Данные команды будут выполнены только если должны быть внесены изменения, при этом они будут выполнены в независимости от того, есть ли они в текущей конфигурации.
lines -		Упорядоченный набор команд, который необходимо сконфигурировать на устройстве. Для достижения идемпотентности необходимо указывать команды так, как они будут выглядеть в running-config после их обработки парсером устройства. псевдоним: commands
match -	Варианты: line ← strict exact none	Данный параметр указывает каким образом сравнивать набор команд с текущей конфигурацией устройства. Если параметр установлен в line, то команды сравниваются построчно. Если параметр установлен в strict, то команды сравниваются с учётом позиции. Если параметр установлен в exact, то набор команд должен в точности совпадать с соответствующей секцией в текущей конфигурации устройства. Если параметр установлен в none, то модуль не будет сравнивать команды с текущей конфигурацией устройства.
merge *boolean*	Варианты: True False ←	Данный параметр включает объединение загруженной конфигурации с candidate-config, текущие параметры будут обновлены, новые параметры будут добавлены. Команда поддержана начиная с версии ПО ESR 1.11.2.
parents -		Упорядоченный набор предков, однозначно идентифицирующих раздел или иерархию, по которым должны проверяться команды. Если параметр не указан, то команды будут проверяться с верхнего уровня иерархии.
replace -	Варианты: line ← block	Данный параметр указывает каким образом отправлять команды на устройство. Если параметр установлен в line, то изменённые строки отправляются на устройство. Если параметр установлен в block, то на устройство будет отправлен блок команд, если какая-то строка будет изменена.
rollback -	Варианты: True ← False	Данный параметр управляет отправкой команды rollback на устройство. Если параметр установлен в true, то модуль отправит команду rollback перед тем, как внести изменения. Если параметр установлен в false, то команда rollback не будет отправлена на устройство.
save_when -	Варианты: always applied never ←	Данный параметр управляет отправкой команды confirm на устройство. Если параметр установлен в always, то команда confirm отправится в независимости от применённых изменений. Если параметр установлен в applied, то команда confirm будет отправлена только в том случае, если на устройстве были применены какие-то изменения в соответствии с параметром apply_when. Если параметр установлен в never, то команда confirm не будет отправлена на устройство и по истечению заданного времени (по умолчанию 600 секунд) устройство произведёт автоматический откат на действующую ранее конфигурацию.
sftp_user -		Данный параметр указывает имя пользователя, с которым необходимо подключиться к устройству по протоколу sftp. Игнорируется, если параметр use_sftp установлен в false.
sftp_password -		Данный параметр указывает пароль, с которым необходимо подключиться к устройству по протоколу sftp с использованием имени пользователя, указанного в параметре sftp_user. Игнорируется, если параметр use_sftp установлен в false.
src -	-	В данном параметре указывается путь к файлу, содержащему конфигурацию маршрутизатора ESR, либо шаблон конфигурации. При использовании данного параметра произойдёт полная замена текущей конфигурации. Если параметр merge будет уставлен в true, то загружаемая конфигурация будет объединена с candidate-config. Загружаемая конфигурация должна иметь преамбулу #!/usr/bin/clish #18 #1.11.2 #18/09/2020 #17:57:44 В противном случает будет использовать построчный режим ввода.
use_sftp boolean	Варианты: True ← False	Данный параметр даёт указание использовать протокол sftp для отправки конфигурации на устройство при использовании параметра src. Для работы необходимо также указать параметры sftp_user и sftp_password.

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

В общем случае возвращаемые значения описаны здесь. Ниже перечислены уникальные для модуля значения:

Значение

Условие

Описание

changed

bool

всегда

Идентификатор внесённых изменений

Пример:

true

backup_path

string

когда параметр

backup установлен в true

Полный путь к файлу бэкапа

Пример:

/ansible/playbooks/backup/esr-1000-config.2019-02-19@11:10:06

commands

list

когда параметр

changed имеет

значение true

Набор команд, которые будут отправлены на устройство

Пример:

['hostname esr-1000', 'ip ssh server', 'ip telnet server']

updates

list

когда параметр

changed имеет

значение true

Набор команд, которые будут отправлены на устройство

Пример:

['hostname esr-1000', 'ip ssh server', 'ip telnet server']

Примеры использования модуля в плейбуках

- name: change_config
  esr_config:
    apply_when: "{{ commit_config | default('modified') }}"
    save_when: "{{ confirm_config | default('applied') }}"
    lines: "{%if configuration is not string %}{{ configuration }}{% else %}{{ configuration | default('') | split('\\n')}}{% endif %}"

- name: get_backup
  esr_config:
    backup: yes

Пример запуска плейбука с модулем esr_config

Плейбук sftp_user_configure:

- name: sftp_user_configure
  tags: sftp_user_configure
  hosts: all
  connection: network_cli
  vars:
    ansible_network_os: eltex.esr.esr
    configuration:
      - "username sftp_user"
      - "ip sftp enable"
      - "password password"
  collections:
    - eltex.esr
  gather_facts: False
  tasks:
    - name: configure sftp user
      tags: configure_sftp_user
      include_tasks: base_tasks/change_config_task.yml

Задача change_config:

- name: change_config
  esr_config:
    apply_when: "{{ commit_config | default('modified') }}"
    save_when: "{{ confirm_config | default('applied') }}"
    lines: "{%if configuration is not string %}{{ configuration }}{% else %}{{ configuration | default('') | split('\\n')}}{% endif %}"

Запуск плейбука:

(venv)user@user:~/eltex/esr/ansible-playbooks$ ansible-playbook -i hosts.ini playbooks/sftp_user_configure.yml -vvv

Результат выполнения плейбука:

PLAYBOOK: sftp_user_configure.yml *************************************************************************************************************************************************************************************************************
1 plays in playbooks/sftp_user_configure.yml

PLAY [show_version] ********************************************************************************************************************************************************************************************************************

TASK [show version data] ***************************************************************************************************************************************************************************************************************
task path: /home/user/eltex/esr/ansible-playbooks/playbooks/sftp_user_configure.yml:12
included: /home/user/eltex/esr/ansible-playbooks/playbooks/base_tasks/change_config.yml for 192.168.35.213

TASK [show_task] ***********************************************************************************************************************************************************************************************************************
task path: /home/user/eltex/esr/ansible-playbooks/playbooks/base_tasks/change_config.yml:1

changed: [192.168.35.213] => {
    "changed": true,
    "commands": [
        "username sftp_user",
        "ip sftp enable",
        "password password"
    ],
    "invocation": {
        "module_args": {
            "after": null,
            "apply_when": "modified",
            "backup": false,
            "before": null,
            "defaults": false,
            "diff_ignore_lines": null,
            "lines": [
                "username sftp_user",
                "ip sftp enable",
                "password password"
            ],
            "match": "line",
            "merge": false,
            "multiline_delimiter": "@",
            "parents": null,
            "provider": null,
            "replace": "line",
            "rollback": true,
            "save_when": "applied",
            "sftp_password": null,
            "sftp_user": null,
            "src": null,
            "use_sftp": false
        }
    },
    "updates": [
        "username sftp_user",
        "ip sftp enable",
        "password password"
    ]
}


PLAY RECAP *****************************************************************************************************************************************************************************************************************************
192.168.35.213             : ok=2    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

Page tree

Управление маршрутизаторами ESR с помощью Ansible

Содержание

Введение

Примечания и предупреждения

Модули

Установка коллекции

Модуль esr_command

Параметры

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

Примеры использования модуля в плейбуках

Пример запуска плейбука с модулем esr_command

Модуль esr_config

Описание

Параметры

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

Примеры использования модуля в плейбуках

Пример запуска плейбука с модулем esr_config