ansible.netcommon.network_cli 连接 – 使用 network_cli 在网络设备上运行命令

注意

此连接插件是 ansible.netcommon 集合 (版本 7.1.0) 的一部分。

如果您使用的是 ansible 包，则可能已安装此集合。它不包含在 ansible-core 中。要检查它是否已安装，请运行 ansible-galaxy collection list。

要安装它，请使用： ansible-galaxy collection install ansible.netcommon。您需要其他要求才能使用此连接插件，请参阅 要求 以了解详细信息。

要在 playbook 中使用它，请指定： ansible.netcommon.network_cli。

ansible.netcommon 1.0.0 中的新增功能

概要

  • 此连接插件通过 SSH 提供与远程设备的连接，并实现 CLI shell。此连接插件通常由网络设备用于向网络设备发送和接收 CLI 命令。

要求

以下要求是在执行此连接的本地控制器节点上所需的。

  • 如果使用 *ssh_type=libssh*，则需要 ansible-pylibssh

参数

参数

注释

become

布尔值

become 选项将指示 CLI 会话尝试在支持它的平台上提升权限。通常这意味着在 CLI 会话中从用户模式转换为 enable 模式。如果将 become 设置为 True，而远程设备不支持权限提升或权限已被提升，则会静默忽略此选项。

可以通过 CLI 使用 --become 或 -b 选项进行配置。

选项

  • false ← (默认)

  • true

配置

  • INI 条目

    [privilege_escalation]
become = false

  • 环境变量：ANSIBLE_BECOME

  • 变量：ansible_become

become_errors

字符串

此选项确定启用 *become* 时如何处理权限提升失败。

设置为 ignore 时，会静默忽略错误。设置为 warn 时，会显示警告消息。默认选项 fail 会触发失败并停止执行。

选项

  • "ignore"

  • "warn"

  • "fail" ← (默认)

配置

  • 变量：ansible_network_become_errors

become_method

字符串

此选项允许为处理权限提升指定 become 方法。通常，become_method 值设置为 enable，但可以定义为其他值。

默认值： "sudo"

配置

  • INI 条目

    [privilege_escalation]
become_method = sudo

  • 环境变量：ANSIBLE_BECOME_METHOD

  • 变量：ansible_become_method

host

字符串

指定要建立 SSH 连接的远程设备 FQDN 或 IP 地址。

默认值： "inventory_hostname"

配置

  • 变量：inventory_hostname

  • 变量：ansible_host

host_key_auto_add

布尔值

默认情况下，Ansible 会在将 SSH 密钥添加到 known_hosts 文件之前提示用户。由于像 network_cli 这样的持久连接在后台进程中运行，因此不会提示用户。通过启用此选项，未知主机密钥将自动添加到 known_hosts 文件。

请确保完全了解在生产系统上启用此选项的安全隐患，因为它可能会造成安全漏洞。

选项

  • false ← (默认)

  • true

配置

host_key_checking

布尔值

如果要避免 Ansible 用于连接到主机的底层工具进行主机密钥检查，请将其设置为“False”

选项

  • false

  • true ← (默认)

配置

import_modules

布尔值

通过启用直接执行来减少 CPU 使用率和网络模块执行时间。模块不会被打包并由 shell 执行，而是将由 Ansible 控制节点使用与 Ansible 进程相同的 python 解释器直接执行。注意-与 asynchronous mode 不兼容。注意-需要 Python 3 和 Ansible 2.9.16 或更高版本。注意-在 Ansible 2.9.x 中，任务中需要完全限定的模块名称。

选项

  • false

  • true ← (默认)

配置

network_cli_retries

整数

连接到远程主机的尝试次数。每次尝试后，重试之间的延迟时间都会以 2 的幂次方秒增加，直到最大尝试次数用尽或触发任何 persistent_command_timeout 或 persistent_connect_timeout 计时器。

默认值： 3

配置

  • INI 条目

    [persistent_connection]
network_cli_retries = 3

  • 环境变量：ANSIBLE_NETWORK_CLI_RETRIES

  • 变量：ansible_network_cli_retries

network_os

字符串

配置设备平台网络操作系统。此值用于加载正确的终端和 cliconf 插件以与远程设备通信。

配置

  • 变量：ansible_network_os

password

字符串

配置在首次建立 SSH 连接时用于向远程设备进行身份验证的用户密码。

配置

  • 变量：ansible_password

  • 变量：ansible_ssh_pass

  • 变量：ansible_ssh_password

persistent_buffer_read_timeout

浮点数 (float)

配置从 Paramiko 通道读取数据等待的时间（以秒为单位），此时间从命令提示符匹配后开始计算。此超时值确保命令提示符匹配正确，并且没有更多数据需要从远程主机接收。

默认值： 0.1

配置

persistent_command_timeout

整数

配置命令从远程设备返回的等待时间（以秒为单位）。如果在命令返回之前超时，连接插件将引发异常并关闭连接。

默认值： 30

配置

persistent_connect_timeout

整数

配置尝试建立持久连接时的等待时间（以秒为单位）。如果在此值过期之前未完成与远程设备的连接，则连接将失败。

默认值： 30

配置

persistent_log_messages

布尔值

此标志将启用将执行的命令和从目标设备接收到的响应记录到 Ansible 日志文件的功能。要使此选项生效，需要将 'log_path' Ansible 配置选项设置为具有写入权限的文件路径。

请务必充分理解启用此选项的安全隐患，因为它可能会通过将敏感信息记录到日志文件中而造成安全漏洞。

选项

  • false ← (默认)

  • true

配置

port

整数

指定远程设备上用于在建立 SSH 连接时侦听连接的端口。

默认值： 22

配置

  • INI 条目

    [defaults]
remote_port = 22

  • 环境变量：ANSIBLE_REMOTE_PORT

  • 变量：ansible_port

private_key_file

字符串

用于在首次建立 SSH 连接时向远程设备进行身份验证的私钥或证书文件。

配置

  • INI 条目

    [defaults]
private_key_file = VALUE

  • 环境变量：ANSIBLE_PRIVATE_KEY_FILE

  • 变量：ansible_private_key_file

remote_user

字符串

在首次建立 SSH 连接时用于向远程设备进行身份验证的用户名。如果未指定 remote_user，则连接将使用登录用户的用户名。

可以通过 CLI 使用 --user 或 -u 选项进行配置。

配置

  • INI 条目

    [defaults]
remote_user = VALUE

  • 环境变量：ANSIBLE_REMOTE_USER

  • 变量：ansible_user

single_user_mode

布尔值

ansible.netcommon 2.0.0 中新增

此选项启用对从目标获取的数据进行缓存以供重复使用。当目标设备进入配置模式时，缓存将失效。

仅适用于已实现此功能的平台。

选项

  • false ← (默认)

  • true

配置

ssh_type

字符串

network_cli 连接插件将使用的 Python 包，用于创建与远程主机的 SSH 连接。

libssh 将使用 ansible-pylibssh 包，需要安装此包才能使用。

paramiko 将使用 paramiko 包来管理 SSH 连接。

auto 如果安装了 ansible-pylibssh 包，则将使用它；否则将回退到 paramiko。

选项

  • "libssh"

  • "paramiko"

  • "auto" ← (默认)

配置

terminal_errors

字符串

ansible.netcommon 3.1.0 中新增

此选项决定如何处理设置终端参数时的失败。

设置为 ignore 时，会静默忽略错误。设置为 warn 时，会显示警告消息。默认选项 fail 会触发失败并停止执行。

选项

  • "ignore"

  • "warn"

  • "fail" ← (默认)

配置

  • 变量：ansible_network_terminal_errors

terminal_inital_prompt_newline

布尔值

此布尔型标志，设置为 *True* 时，如果匹配 *terminal_initial_prompt* 中的任何值，则会在响应中发送换行符。

选项

  • false

  • true ← (默认)

配置

  • 变量：ansible_terminal_initial_prompt_newline

terminal_initial_answer

列表 / 元素=字符串

如果匹配 terminal_initial_prompt，则要回复的答案。该值可以是单个答案或多个答案的列表，用于多个 terminal_initial_prompt。如果登录菜单有多个提示，则提示和预期答案的顺序应相同，并且如果预期匹配 terminal_initial_prompt 中的所有值，则 *terminal_prompt_checkall* 的值应设置为 *True*；如果只需要匹配任何一个登录提示，则应设置为 *False*。

配置

  • 变量：ansible_terminal_initial_answer

terminal_initial_prompt

列表 / 元素=字符串

单个正则表达式模式或模式序列，用于评估在初始登录到远程主机时的预期提示。

配置

  • 变量：ansible_terminal_initial_prompt

terminal_initial_prompt_checkall

布尔值

默认情况下，该值设置为 *False*，如果匹配 terminal_initial_prompt 选项中提到的任何一个提示，则不会检查其他提示。设置为 *True* 时，它将按给定的顺序检查 terminal_initial_prompt 选项中提到的所有提示，并且如果远程主机未收到所有提示，则会导致超时。

选项

  • false ← (默认)

  • true

配置

  • 变量：ansible_terminal_initial_prompt_checkall

terminal_stderr_re

列表 / 元素=字典

此选项提供正则表达式模式和可选标志，用于从接收到的响应块中匹配错误字符串。此选项接受 pattern 和 flags 键。pattern 的值是用于匹配响应的 Python 正则表达式模式，flags 的值是 *re.compile* Python 方法的 *flags* 参数接受的值，用于控制正则表达式与响应匹配的方式，例如 *'re.I'*。

配置

  • 变量：ansible_terminal_stderr_re

terminal_stdout_re

列表 / 元素=字典

单个正则表达式模式或模式序列以及可选标志，用于从接收到的响应块中匹配命令提示符。此选项接受 pattern 和 flags 键。pattern 的值是用于匹配响应的 Python 正则表达式模式，flags 的值是 *re.compile* Python 方法的 *flags* 参数接受的值，用于控制正则表达式与响应匹配的方式，例如 *'re.I'*。

配置

  • 变量：ansible_terminal_stdout_re

作者

  • Ansible 网络团队 (@ansible-network)

提示

每个条目类型的配置项具有从低到高的优先级顺序。例如，列表中较低的变量将覆盖列表中较高的变量。