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

• Введение
• Как устранять неполадки
  • Включение ведения журнала сетевых операций и чтение файла журнала
  • Включение ведения журнала взаимодействия с сетевым устройством
  • Изоляция ошибки
• Категория «проблема с путем сокета»
• Категория «невозможно открыть оболочку»
  • Ошибка: «[Errno -2] Имя или служба неизвестны»
  • Ошибка: «Ошибка аутентификации»
  • Ошибка: «подключение к хосту <hostname> вернуло ошибку» или «Неверный адрес»
  • Ошибка: «Доступные методы аутентификации отсутствуют»
  • Очистка постоянных подключений
• Проблемы с таймаутами
  • Таймаут бездействия постоянного подключения
  • Таймаут команды
  • Таймаут повторных попыток постоянного подключения
• Проблемы с playbook
  • Ошибка: «Невозможно перейти в конфигурационный режим»
• Проблемы с прокси
  • delegate_to против ProxyCommand
  • Использование бастионного/переключающего хоста с подключением netconf
  • Включение настроек бастионного хоста
  • Пример файла конфигурации ssh (~/.ssh/config)
• Разные проблемы
  • Периодические сбои при использовании типа подключения network_cli

Введение

Начиная с версии Ansible 2.1, теперь можно использовать знакомые модели Ansible для разработки playbook и модулей для управления гетерогенными сетевыми устройствами. Ansible поддерживает все большее количество сетевых устройств, используя как CLI через SSH, так и API (если доступен) транспорт.

Этот раздел описывает, как отлаживать и устранять неполадки с сетевыми модулями в Ansible 2.3.

Как устранять неполадки

Этот раздел посвящен устранению проблем с сетевыми модулями.

Ошибки, как правило, попадают в одну из следующих категорий:

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

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

Ansible 2.3 имеет улучшенный журнал, который помогает диагностировать и устранять проблемы с сетевыми модулями 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 2.8 имеет дополнительный журнал взаимодействия с устройствами в файле журнала, который помогает диагностировать и устранять проблемы с сетевыми модулями 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
  ios_command:
    commands:
      - show version
  vars:
    ansible_persistent_log_messages: True

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

[persistent_connection]
log_messages = True

или включите переменную окружения ANSIBLE_PERSISTENT_LOG_MESSAGES

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

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

Изоляция ошибки

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

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

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

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

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

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

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

• Подключаемся к switch1.example.net, указанному в файле инвентаризации inventory
• Используем модуль 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 4*v for connection level verbosity
ansible -m eos_command -a 'commands=?' -i inventory switch1.example.net -e 'ansible_connection=local' -u admin -k

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

Категория «проблема с путем сокета»

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

Сообщения socket_path does not exist or cannot be found и unable to connect to socket появились в Ansible 2.5. Эти сообщения указывают на то, что сокет, используемый для связи с удаленным сетевым устройством, недоступен или не существует.

Например:

fatal: [spine02]: FAILED! => {
    "changed": false,
    "failed": true,
    "module_stderr": "Traceback (most recent call last):\n  File \"/tmp/ansible_TSqk5J/ansible_modlib.zip/ansible/module_utils/connection.py\", line 115, in _exec_jsonrpc\nansible.module_utils.connection.ConnectionError: socket_path does not exist or cannot be found\n",
    "module_stdout": "",
    "msg": "MODULE FAILURE",
    "rc": 1
}

или

fatal: [spine02]: FAILED! => {
    "changed": false,
    "failed": true,
    "module_stderr": "Traceback (most recent call last):\n  File \"/tmp/ansible_TSqk5J/ansible_modlib.zip/ansible/module_utils/connection.py\", line 123, in _exec_jsonrpc\nansible.module_utils.connection.ConnectionError: unable to connect to socket\n",
    "module_stdout": "",
    "msg": "MODULE FAILURE",
    "rc": 1
}

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

Следуйте шагам, описанным в включении протоколирования сетевого трафика.

Если в файле журнала обнаружено следующее сообщение об ошибке:

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

или

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

Следуйте шагам, описанным в проблемах с таймаутами.

Категория «Не удается открыть оболочку»

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

Сообщение unable to open shell появилось в Ansible 2.3. Это сообщение означает, что демону ansible-connection не удалось успешно связаться с удаленным сетевым устройством. Обычно это указывает на проблему с аутентификацией. Это сообщение общего характера, поэтому необходимо включить :ref:logging`a_note_about_logging`, чтобы найти первопричину проблемы.

Например:

TASK [prepare_eos_tests : enable cli on remote device] **************************************************
fatal: [veos01]: FAILED! => {"changed": false, "failed": true, "msg": "unable to open shell"}

или:

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

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

Следуйте шагам, описанным в enable_network_logging.

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

Ошибка: «[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, возможно, библиотека SSH Python (paramiko), используемая 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 (Таймаут команды на задачу): Увеличение таймаута команды на основе задач. Все сетевые модули поддерживают значение таймаута, которое можно устанавливать на основе каждой задачи. Значение таймаута определяет время в секундах, прежде чем задача завершится неудачно, если команда не вернулась.

  Для локального подключения:

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

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

  Для network_cli, netconf типов подключения (применимо начиная с 2.7):

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

  - name: save running-config
    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

Проблемы с playbook

Этот раздел описывает проблемы, вызванные проблемами самого Playbook.

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

Платформы: eos и ios

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

Например:

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

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

Добавьте authorize: yes в задачу. Например:

- name: configure hostname
  ios_system:
    provider:
      hostname: foo
      authorize: yes
  register: result

Если для входа в привилегированный режим требуется пароль, его можно указать с помощью auth_pass; если auth_pass не задано, будет использоваться переменная окружения ANSIBLE_NET_AUTHORIZE.

Добавьте authorize: yes в задачу. Например:

- name: configure hostname
  ios_system:
  provider:
    hostname: foo
    authorize: yes
    auth_pass: "{{ mypasswordvar }}"
register: result

Проблемы с прокси

delegate_to vs ProxyCommand

Новая система подключения для сетевых модулей в Ansible 2.3, использующая транспорт cli, больше не поддерживает директиву delegate_to. Для использования бастиона или промежуточного хоста для подключения к сетевым устройствам через транспорт 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.
# i.e. 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=netconf
ansible_network_os=junos
ansible_user=myuser
ansible_password=!vault...

Разные проблемы

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

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

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

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

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

[persistent_connection]
buffer_read_timeout = 2

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