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

Введение

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

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

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

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

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

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

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

Ansible 2.3 имеет улучшенную систему ведения журнала для диагностики и устранения неполадок, связанных с модулями 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, а не удаленный пользователь, от имени которого вы пытаетесь подключиться
• 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-playbook --limit switch1.example.net...
• Использование ад-хок 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 10 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 не удалось успешно подключиться к удаленному сетевому устройству. Это обычно указывает на проблему с аутентификацией. Это «глобальное» сообщение, а значит, необходимо включить ведение журнала, чтобы найти исходные проблемы.

Например:

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",
}

Рекомендации по решению:

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

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

Ошибка: «[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 секунд), просто удалите файл сокета.

Проблемы с таймаутами

Таймауты

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

Например:

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

Таймаут команды: Например:

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

Рекомендации по решению:

Вариант 1: Увеличение значения таймаута команды в файле конфигурации или путем установки переменной окружения. Примечание: Это значение должно быть меньше, чем таймаут бездействия постоянного подключения, то есть connect_timeout

export ANSIBLE_PERSISTENT_COMMAND_TIMEOUT=30

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

[persistent_connection]
command_timeout = 30

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

Например:

Рекомендации по решению:

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

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

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

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.

Ошибка: «Неверная спецификация подключения, ожидалось connection=local, получено ssh»

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

Модули сети требуют, чтобы подключение было установлено на local. Любое другое значение подключения приведет к сбою playbook. Ansible теперь обнаружит это условие и вернёт сообщение об ошибке:

fatal: [nxos01]: FAILED! => {
    "changed": false,
    "failed": true,
    "msg": "invalid connection specified, expected connection=local, got ssh"
}

Чтобы исправить эту проблему, установите значение connection на local с помощью одного из следующих методов:

• Установите для playbook использование connection: local
• Установите для задачи использование connection: local
• Запустите ansible-playbook с параметром -c local

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

Платформы: 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 против 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 в приведенном выше примере.