Руководство по отладке и устранению неполадок сети

Включение журналов сетевой активности и чтение файла журнала

Платформы: Любые

Ansible включает ведение журналов для диагностики и устранения неполадок, связанных с модулями Ansible Networking.

Поскольку журналы очень подробные, они отключены по умолчанию. Их можно включить с помощью опций ANSIBLE_LOG_PATH и ANSIBLE_DEBUG на контроллере Ansible, то есть на машине, на которой выполняется ansible-playbook.

Перед запуском ansible-playbook выполните следующие команды для включения ведения журналов:

# Specify the location for the log file
export ANSIBLE_LOG_PATH=~/ansible.log
# Enable Debug
export ANSIBLE_DEBUG=True

# Run with 4*v for connection level verbosity
ansible-playbook -vvvv ...

После завершения работы Ansible вы можете просмотреть файл журнала, созданный на контроллере Ansible:

less $ANSIBLE_LOG_PATH

2017-03-30 13:19:52,740 p=28990 u=fred |  creating new control socket for host veos01:22 as user admin
2017-03-30 13:19:52,741 p=28990 u=fred |  control socket path is /home/fred/.ansible/pc/ca5960d27a
2017-03-30 13:19:52,741 p=28990 u=fred |  current working directory is /home/fred/ansible/test/integration
2017-03-30 13:19:52,741 p=28990 u=fred |  using connection plugin network_cli
...
2017-03-30 13:20:14,771 paramiko.transport userauth is OK
2017-03-30 13:20:15,283 paramiko.transport Authentication (keyboard-interactive) successful!
2017-03-30 13:20:15,302 p=28990 u=fred |  ssh connection done, setting terminal
2017-03-30 13:20:15,321 p=28990 u=fred |  ssh connection has completed successfully
2017-03-30 13:20:15,322 p=28990 u=fred |  connection established to veos01 in 0:00:22.580626

Обратите внимание на:

• p=28990 — это идентификатор процесса (PID) процесса ansible-connection
• u=fred — это пользователь running ansible, а не удалённый пользователь, под которым вы пытаетесь подключиться
• creating new control socket for host veos01:22 as user admin — хост:порт как пользователь
• control socket path is — расположение на диске, где создаётся сокет постоянного подключения
• using connection plugin network_cli — сообщает о том, что используется постоянное подключение
• connection established to veos01 in 0:00:22.580626 — время, затраченное на получение оболочки на удалённом устройстве

Поскольку файлы журналов подробны, вы можете использовать команду grep для поиска конкретной информации. Например, после того, как вы определили pid из строки creating new control socket for host, вы можете искать другие записи журнала подключения:

grep "p=28990" $ANSIBLE_LOG_PATH

Включение ведения журнала взаимодействия с сетевым устройством

Платформы: Любые

Ansible записывает взаимодействие с устройствами в файл журнала, что помогает диагностировать и устранять проблемы, связанные с модулями Ansible Networking. Сообщения записываются в файл, указанный опцией log_path в конфигурационном файле Ansible или путем задания ANSIBLE_LOG_PATH.

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

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

Перед запуском ansible-playbook выполните следующие команды для включения ведения журналов:

# Specify the location for the log file
export ANSIBLE_LOG_PATH=~/ansible.log

Включение ведения журнала взаимодействия для заданной задачи

- name: get version information
  cisco.ios.ios_command:
    commands:
      - show version
  vars:
    ansible_persistent_log_messages: True

Чтобы сделать это глобальной настройкой, добавьте следующее в ваш файл ansible.cfg:

[persistent_connection]
log_messages = True

или включите переменную среды ANSIBLE_PERSISTENT_LOG_MESSAGES:

# Enable device interaction logging
export ANSIBLE_PERSISTENT_LOG_MESSAGES=True

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

После завершения работы Ansible вы можете просмотреть созданный на контроллере Ansible файл журнала

Изолирование ошибки

Платформы: Любые

Как и при любом поиске неисправностей, важно максимально упростить тестовый случай.

Для Ansible это можно сделать, убедившись, что вы работаете только с одним удаленным устройством:

• Используя ansible-playbook --limit switch1.example.net...
• Используя команду ad hoc ansible

ad hoc означает запуск Ansible для выполнения быстрой команды с помощью /usr/bin/ansible, а не языка оркестрации, который является /usr/bin/ansible-playbook. В этом случае мы можем убедиться в подключении, попытавшись выполнить одну команду на удаленном устройстве:

ansible -m arista.eos.eos_command -a 'commands=?' -i inventory switch1.example.net -e 'ansible_connection=ansible.netcommon.network_cli' -u admin -k

В приведенном выше примере:

• подключаемся к switch1.example.net, указанному в файле инвентаризации inventory
• используем модуль arista.eos.eos_command
• выполняем команду ?
• подключаемся под пользователем admin
• запрашиваем у команды ansible пароль SSH, указав -k

Если ключи SSH настроены правильно, параметр -k указывать не нужно.

Если подключение по-прежнему не удается, вы можете объединить его с параметром enable_network_logging. Например:

# Specify the location for the log file
export ANSIBLE_LOG_PATH=~/ansible.log
# Enable Debug
export ANSIBLE_DEBUG=True
# Run with ``-vvvv`` for connection level verbosity
ansible -m arista.eos.eos_command -a 'commands=?' -i inventory switch1.example.net -e 'ansible_connection=ansible.netcommon.network_cli' -u admin -k

Затем просмотрите файл журнала и найдите соответствующее сообщение об ошибке в остальной части документа.

Ошибка: «[Errno -2] Имя или служба неизвестны»

Платформы: Любые

Указывает, что удалённый хост, к которому вы пытаетесь подключиться, недоступен.

Например:

2017-04-04 11:39:48,147 p=15299 u=fred |  control socket path is /home/fred/.ansible/pc/ca5960d27a
2017-04-04 11:39:48,147 p=15299 u=fred |  current working directory is /home/fred/git/ansible-inc/stable-2.3/test/integration
2017-04-04 11:39:48,147 p=15299 u=fred |  using connection plugin network_cli
2017-04-04 11:39:48,340 p=15299 u=fred |  connecting to host veos01 returned an error
2017-04-04 11:39:48,340 p=15299 u=fred |  [Errno -2] Name or service not known

Предложения по решению:

• Если вы используете опции provider:, убедитесь, что её подопция host: настроена корректно.
• Если вы не используете provider: или аргументы верхнего уровня, убедитесь, что ваш файл инвентаризации корректен.

Ошибка: «Аутентификация не удалась»

Платформы: Любые

Возникает, если предоставленные учетные данные (имя пользователя, пароли или ключи SSH) для ansible-connection (через ansible или ansible-playbook) не могут быть использованы для подключения к удалённому устройству.

Например:

<ios01> ESTABLISH CONNECTION FOR USER: cisco on PORT 22 TO ios01
<ios01> Authentication failed.

Предложения по решению:

Если вы указываете учетные данные через password: (прямо или через provider:) или переменную окружения ANSIBLE_NET_PASSWORD, возможно, paramiko (библиотека Python SSH, используемая Ansible) использует ключи SSH, а поэтому указанные вами учетные данные игнорируются. Чтобы выяснить это, отключите поиск ключей. Это можно сделать так:

export ANSIBLE_PARAMIKO_LOOK_FOR_KEYS=False

Чтобы сделать это постоянным изменением, добавьте следующее в ваш файл ansible.cfg:

[paramiko_connection]
look_for_keys = False

Ошибка: «подключение к хосту <hostname> вернуло ошибку» или «Неверный адрес»

Это может произойти, если отпечаток SSH не был добавлен в файл известных хостов Paramiko (библиотека Python SSH).

При использовании постоянных соединений с Paramiko подключение выполняется в фоновом процессе. Если у хоста ещё нет валидного ключа SSH, Ansible по умолчанию предложит добавить ключ хоста. Это приведёт к ошибке подключений, выполняемых в фоновых процессах.

Например:

2017-04-04 12:06:03,486 p=17981 u=fred |  using connection plugin network_cli
2017-04-04 12:06:04,680 p=17981 u=fred |  connecting to host veos01 returned an error
2017-04-04 12:06:04,682 p=17981 u=fred |  (14, 'Bad address')
2017-04-04 12:06:33,519 p=17981 u=fred |  number of connection attempts exceeded, unable to connect to control socket
2017-04-04 12:06:33,520 p=17981 u=fred |  persistent_connect_interval=1, persistent_connect_retries=30

Предложения по решению:

Используйте ssh-keyscan для предварительной заполнения known_hosts. Необходимо убедиться в корректности ключей.

ssh-keyscan veos01

или

Вы можете указать Ansible автоматически принимать ключи

Метод переменной окружения:

export ANSIBLE_PARAMIKO_HOST_KEY_AUTO_ADD=True
ansible-playbook ...

Метод ansible.cfg:

ansible.cfg

[paramiko_connection]
host_key_auto_add = True

Ошибка: «Нет доступных методов аутентификации»

Например:

2017-04-04 12:19:05,670 p=18591 u=fred |  creating new control socket for host veos01:None as user admin
2017-04-04 12:19:05,670 p=18591 u=fred |  control socket path is /home/fred/.ansible/pc/ca5960d27a
2017-04-04 12:19:05,670 p=18591 u=fred |  current working directory is /home/fred/git/ansible-inc/ansible-workspace-2/test/integration
2017-04-04 12:19:05,670 p=18591 u=fred |  using connection plugin network_cli
2017-04-04 12:19:06,606 p=18591 u=fred |  connecting to host veos01 returned an error
2017-04-04 12:19:06,606 p=18591 u=fred |  No authentication methods available
2017-04-04 12:19:35,708 p=18591 u=fred |  connect retry timeout expired, unable to connect to control socket
2017-04-04 12:19:35,709 p=18591 u=fred |  persistent_connect_retry_timeout is 15 secs

Предложения по решению:

Не указан пароль или ключ SSH

Очистка постоянных подключений

Платформы: Любые

В Ansible 2.3 сокеты постоянного подключения хранятся в ~/.ansible/pc для всех сетевых устройств. При запуске Ansible playbook постоянное сокет-соединение отображается при указании подробного вывода.

<switch> socket_path: /home/fred/.ansible/pc/f64ddfa760

Для очистки постоянного подключения перед его истечением (значение таймаута по умолчанию — 30 секунд бездействия), достаточно удалить файл сокета.

Таймаут бездействия постоянного подключения

По умолчанию, ANSIBLE_PERSISTENT_CONNECT_TIMEOUT установлен в 30 (секунд). Вы можете увидеть следующую ошибку, если это значение слишком низкое:

2017-04-04 12:19:05,670 p=18591 u=fred |  persistent connection idle timeout triggered, timeout value is 30 secs

Предложения по решению:

Увеличьте значение таймаута бездействия постоянного подключения:

export ANSIBLE_PERSISTENT_CONNECT_TIMEOUT=60

Чтобы сделать это постоянным изменением, добавьте следующее в ваш файл ansible.cfg:

[persistent_connection]
connect_timeout = 60

Таймаут команды

По умолчанию, ANSIBLE_PERSISTENT_COMMAND_TIMEOUT установлен в 30 (секунд). В предыдущих версиях Ansible это значение по умолчанию было 10 секунд. Вы можете увидеть следующую ошибку, если это значение слишком низкое:

2017-04-04 12:19:05,670 p=18591 u=fred |  command timeout triggered, timeout value is 30 secs

Предложения по решению:

• Вариант 1 (Глобальная настройка таймаута команды): Увеличьте значение таймаута команды в файле конфигурации или заданием переменной окружения.

  export ANSIBLE_PERSISTENT_COMMAND_TIMEOUT=60
  

  Чтобы сделать это постоянным изменением, добавьте следующее в ваш файл ansible.cfg:

  [persistent_connection]
  command_timeout = 60
  

• Вариант 2 (Таймаут команды на задачу): Увеличение таймаута команды на основе задачи. Все сетевые модули поддерживают значение таймаута, которое может быть установлено на основе каждой задачи. Значение таймаута определяет время в секундах, прежде чем задача завершится с ошибкой, если команда не вернула результат.

  Для локального типа соединения:

  Предложения по решению:

  Некоторые модули поддерживают опцию timeout, которая отличается от ключевого слова timeout для задач.

  - name: save running-config
    cisco.ios.ios_command:
      commands: copy running-config startup-config
      provider: "{{ cli }}"
      timeout: 30
  

  Предложения по решению:

  Если модуль не поддерживает опцию timeout напрямую, большинство плагинов сетевого подключения могут включить аналогичную функциональность с переменной ansible_command_timeout.

  - name: save running-config
    cisco.ios.ios_command:
      commands: copy running-config startup-config
    vars:
      ansible_command_timeout: 60
  

Некоторые операции занимают больше времени, чем стандартные 30 секунд. Хороший пример — сохранение текущей конфигурации на устройствах IOS в конфигурацию по умолчанию. В этом случае изменение значения таймаута с 30 секунд до 60 секунд предотвратит завершение задачи с ошибкой, прежде чем команда выполнится успешно.

Таймаут повторного подключения постоянного соединения

По умолчанию, ANSIBLE_PERSISTENT_CONNECT_RETRY_TIMEOUT установлен в 15 (секунд). Вы можете увидеть следующую ошибку, если это значение слишком низкое:

2017-04-04 12:19:35,708 p=18591 u=fred |  connect retry timeout expired, unable to connect to control socket
2017-04-04 12:19:35,709 p=18591 u=fred |  persistent_connect_retry_timeout is 15 secs

Предложения по решению:

Увеличьте значение таймаута бездействия постоянного соединения. Примечание: это значение должно быть больше, чем значение таймаута SSH (значение таймаута в разделе «Параметры» в файле конфигурации) и меньше, чем значение таймаута бездействия постоянного подключения (connect_timeout).

export ANSIBLE_PERSISTENT_CONNECT_RETRY_TIMEOUT=30

Чтобы сделать это постоянным изменением, добавьте следующее в ваш файл ansible.cfg:

[persistent_connection]
connect_retry_timeout = 30

Проблема с таймаутом из-за специфичной для платформы страницы входа с типом подключения network_cli

В Ansible 2.9 и более поздних версиях добавлены опции конфигурации плагина подключения network_cli для обработки специфичных для платформы меню входа. Эти опции можно задать как переменные группы/хоста или задачи.

Пример: Обработка однократных запросов на вход с переменными хоста

$ cat host_vars/<hostname>.yaml
---
ansible_terminal_initial_prompt:
  - "Connect to a host"
ansible_terminal_initial_answer:
  - "3"

Пример: Обработка множественных запросов на вход с переменными хоста

$ cat host_vars/<inventory-hostname>.yaml
---
ansible_terminal_initial_prompt:
  - "Press any key to enter main menu"
  - "Connect to a host"
ansible_terminal_initial_answer:
  - "\\r"
  - "3"
ansible_terminal_initial_prompt_checkall: True

Для обработки множественных запросов на вход:

• Значения ansible_terminal_initial_prompt и ansible_terminal_initial_answer должны быть списком.
• Последовательность запросов должна соответствовать последовательности ответов.
• Значение ansible_terminal_initial_prompt_checkall должно быть установлено в True.

Ошибка: «Невозможно войти в конфигурационный режим»

Платформы: Arista EOS и Cisco IOS

Возникает при попытке выполнения задачи, требующей привилегированного режима в оболочке пользовательского режима.

Например:

TASK [ios_system : configure name_servers] *****************************************************************************
task path:
fatal: [ios-csr1000v]: FAILED! => {
    "changed": false,
    "failed": true,
   "msg": "unable to enter configuration mode",
}

Предложения по решению:

Используйте connection: ansible.netcommon.network_cli и become: true

delegate_to по сравнению с ProxyCommand

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

Для использования ProxyCommand, настройте параметры прокси в файле инвентаризации Ansible для указания хоста-прокси.

[nxos]
nxos01
nxos02

[nxos:vars]
ansible_ssh_common_args='-o ProxyCommand="ssh -W %h:%p -q bastion01"'

При указанной конфигурации просто выполните playbook, как обычно, без дополнительных изменений. Сетевой модуль теперь подключится к сетевому устройству, сначала подключившись к хосту, указанному в ansible_ssh_common_args, что является bastion01 в данном примере.

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

export ANSIBLE_SSH_ARGS='-o ProxyCommand="ssh -W %h:%p -q bastion01"'

Использование бастионного/переходного хоста с подключением netconf

Включение параметра переходного хоста

Бастионный/переходный хост с подключением netconf можно включить, выполнив:

• Установка переменной Ansible ansible_netconf_ssh_config в значение True или путь к пользовательскому файлу конфигурации SSH
• Установка переменной окружения ANSIBLE_NETCONF_SSH_CONFIG в значение True или путь к пользовательскому файлу конфигурации SSH
• Установка ssh_config = 1 или ssh_config = <ssh-file-path> в разделе netconf_connection

Если переменная конфигурации установлена в 1, proxycommand и другие переменные SSH читаются из стандартного файла конфигурации SSH (~/.ssh/config).

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

Пример файла конфигурации ssh (~/.ssh/config)

Host jumphost
  HostName jumphost.domain.name.com
  User jumphost-user
  IdentityFile "/path/to/ssh-key.pem"
  Port 22

# Note: Due to the way that Paramiko reads the SSH Config file,
# you need to specify the NETCONF port that the host uses.
# In other words, it does not automatically use ansible_port
# As a result you need either:

Host junos01
  HostName junos01
  ProxyCommand ssh -W %h:22 jumphost

# OR

Host junos01
  HostName junos01
  ProxyCommand ssh -W %h:830 jumphost

# Depending on the netconf port used.

Пример файла инвентаризации Ansible

[junos]
junos01

[junos:vars]
ansible_connection=ansible.netcommon.netconf
ansible_network_os=junipernetworks.junos.junos
ansible_user=myuser
ansible_password=!vault...

Периодические сбои при использовании типа подключения ansible.netcommon.network_cli

Если команда, полученная в ответ, не соответствует правильно в плагине подключения ansible.netcommon.network_cli, задача может периодически завершаться с усечённым ответом или сообщением об ошибке operation requires privilege escalation. Начиная с версии 2.7.1, добавлен новый таймер чтения буфера, чтобы гарантировать правильное соответствие запросов и отправку полного ответа в выходные данные. Значение таймера по умолчанию составляет 0,2 секунды и может быть настроено для каждой задачи или глобально в секундах.

Пример настройки таймера для задачи

- name: gather ios facts
  cisco.ios.ios_facts:
    gather_subset: all
  register: result
  vars:
    ansible_buffer_read_timeout: 2

Чтобы сделать это глобальной настройкой, добавьте следующее в ваш файл ansible.cfg:

[persistent_connection]
buffer_read_timeout = 2

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

Ошибка задачи из-за несовпадения регулярного выражения ошибки в ответе команды с использованием типа подключения ansible.netcommon.network_cli

В Ansible 2.9 и более поздних версиях добавлены параметры конфигурации плагина подключения ansible.netcommon.network_cli для обработки регулярных выражений stdout и stderr для определения, содержит ли ответ на выполнение команды нормальный ответ или ответ об ошибке. Эти параметры можно задать в переменных группы/хоста или как переменные задач.

Пример: для несовпадающего ответа об ошибке

- name: fetch logs from remote host
  cisco.ios.ios_command:
    commands:
      - show logging

Вывод выполнения книги задач:

TASK [first fetch logs] ********************************************************
fatal: [ios01]: FAILED! => {
    "changed": false,
    "msg": "RF Name:\r\n\r\n <--nsip-->
           \"IPSEC-3-REPLAY_ERROR: Test log\"\r\n*Aug  1 08:36:18.483: %SYS-7-USERLOG_DEBUG:
            Message from tty578(user id: ansible): test\r\nan-ios-02#"}

Рекомендации по устранению:

Измените регулярное выражение ошибки для отдельной задачи.

- name: fetch logs from remote host
  cisco.ios.ios_command:
    commands:
      - show logging
  vars:
    ansible_terminal_stderr_re:
      - pattern: 'connection timed out'
        flags: 're.I'

Параметры регулярного выражения плагина терминала ansible_terminal_stderr_re и ansible_terminal_stdout_re имеют pattern и flags в качестве ключей. Значение ключа flags должно быть значением, которое принимается методом re.compile языка Python.

Периодические сбои при использовании типа подключения ansible.netcommon.network_cli из-за медленной сети или удалённого целевого хоста

В Ansible 2.9 и более поздних версиях добавлен параметр конфигурации плагина подключения ansible.netcommon.network_cli для управления количеством попыток подключения к удалённому хосту. По умолчанию количество попыток равно трём. После каждой попытки повтора задержка между повторами увеличивается на степень 2 в секундах, пока не исчерпаны максимальное количество попыток или не сработают таймеры persistent_command_timeout или persistent_connect_timeout.

Чтобы сделать это глобальной настройкой, добавьте следующее в ваш файл ansible.cfg:

[persistent_connection]
network_cli_retries = 5