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

Включение журналирования сетевых операций и чтение файла журнала

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

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

Поскольку журналирование создаёт очень подробные записи, по умолчанию оно отключено. Его можно включить с помощью параметров 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. Сообщения записываются в файл, указанный параметром конфигурации 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...
• Используйте команду 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 (библиотека SSH для Python, используемая Ansible) применяет ключи SSH, поэтому указанные вами учётные данные игнорируются. Чтобы проверить, так ли это, отключите параметр «искать ключи». Это можно сделать следующим образом:

export ANSIBLE_PARAMIKO_LOOK_FOR_KEYS=False

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

[paramiko_connection]
look_for_keys = False

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

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

При использовании постоянных подключений с 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 сокет постоянного подключения отображается, если указан подробный вывод.

<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 (значения тайм-аута в разделе defaults файла конфигурации) и меньше значения тайм-аута бездействия постоянного подключения (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_paramiko_proxy_command='-o ProxyCommand="ssh -W %h:%p -q bastion01"'

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

Также можно задать цель прокси для всех узлов с помощью переменных среды.

export ANSIBLE_PARAMIKO_PROXY_COMMAND='-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

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

Сбой задачи из-за несовпадения регулярного выражения ошибки в ответе команды при использовании типа подключения 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 должно быть допустимым для метода Python re.compile.

Периодический сбой при использовании типа подключения 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