网络调试和故障排除指南

本节讨论如何在 Ansible 中调试和排除网络模块的故障。

类别“无法打开 shell”

平台： 任何

无法打开 shell 消息表示 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",
}

解决建议

按照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: 或顶级参数，请确保您的清单文件正确。

错误：“身份验证失败”

平台： 任何

如果传递给 ansible-connection (通过 ansible 或 ansible-playbook) 的凭据（用户名、密码或 ssh 密钥）无法用于连接到远程设备，则会发生此错误。

例如

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

解决建议

如果您正在通过 password: (直接或通过 provider:) 或环境变量 ANSIBLE_NET_PASSWORD 指定凭据，则 paramiko (Ansible 使用的 Python SSH 库) 可能正在使用 ssh 密钥，因此您指定的凭据将被忽略。要找出是否是这种情况，请禁用“查找密钥”。可以通过以下方式进行此操作

export ANSIBLE_PARAMIKO_LOOK_FOR_KEYS=False

要使此更改永久生效，请将以下内容添加到您的 ansible.cfg 文件中

[paramiko_connection]
look_for_keys = False

错误：“连接到主机返回一个错误”或“错误的地址”

如果 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

清除持久连接 

平台： 任何

在 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 超时值（配置文件 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。

注意

如果在连接初始化时没有从远程主机收到序列中的所有提示，则会导致超时。

Playbook 问题 

本节详细介绍了由 Playbook 本身的问题引起的问题。

错误：“无法进入配置模式”

平台： Arista EOS 和 Cisco IOS

当您尝试在用户模式 shell 中运行需要特权模式的任务时，会发生这种情况。

例如

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 vs 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 连接：

将 Ansible 变量 ansible_netconf_ssh_config 设置为 True 或自定义 ssh 配置文件路径
将环境变量 ANSIBLE_NETCONF_SSH_CONFIG 设置为 True 或自定义 ssh 配置文件路径
在 netconf_connection 部分下设置 ssh_config = 1 或 ssh_config = <ssh-file-path>

如果配置变量设置为 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...

注意

通过变量使用 ProxyCommand 进行密码验证

按照设计，SSH 不支持通过环境变量提供密码。这样做是为了防止机密信息泄露，例如在 ps 输出中。

我们建议尽可能使用 SSH 密钥，如果需要，可以使用 ssh-agent，而不是密码。

如果在 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

Playbook 运行输出

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

网络调试和故障排除指南

如何进行故障排除 

启用网络日志记录以及如何读取日志文件 

启用网络设备交互日志记录 

隔离错误 

排查套接字路径问题 

类别“无法打开 shell”

错误：“[Errno -2] 名称或服务未知”

错误：“身份验证失败”

错误：“连接到主机返回一个错误”或“错误的地址”

错误：“没有可用的身份验证方法”

清除持久连接 

超时问题 

持久连接空闲超时 

命令超时 

持久连接重试超时 

Playbook 问题 

错误：“无法进入配置模式”

代理问题 

delegate_to vs ProxyCommand 

使用堡垒/跳转主机进行 netconf 连接 

启用跳转主机设置 

示例 ssh 配置文件（~/.ssh/config）

其他问题 

使用 `ansible.netcommon.network_cli` 连接类型时出现间歇性故障 

由于使用 `ansible.netcommon.network_cli` 连接类型时，命令响应中不匹配的错误正则表达式而导致的任务失败 

由于网络速度较慢或远程目标主机较慢，使用 `ansible.netcommon.network_cli` 连接类型时出现间歇性故障 