ansible.builtin.ssh 连接 – 通过 SSH 客户端二进制文件连接

注意

此连接插件是 ansible-core 的一部分，包含在所有 Ansible 安装中。在大多数情况下，您可以使用简短的插件名称 ssh。但是，我们建议您使用完全限定的集合名称 (FQCN) ansible.builtin.ssh，以便轻松链接到插件文档并避免与可能具有相同连接插件名称的其他集合冲突。

概要

  • 此连接插件允许 Ansible 通过正常的 SSH 命令行与目标机器通信。

  • Ansible 不提供通道来允许用户和 SSH 进程之间的通信，以便在使用此连接插件（这是默认设置）时手动接受密码来解密 SSH 密钥。强烈建议使用 ssh-agent。

参数

参数

注释

control_path

字符串

这是保存 SSH 的 ControlPath 套接字的位置，它使用 SSH 的变量替换。

从 2.3 版本开始，如果为空（默认值），ansible 将生成一个唯一的哈希值。使用 ``%(directory)s`` 指示在哪里使用 control dir 路径设置。

2.3 版本之前，默认为 ``control_path=%(directory)s/ansible-ssh-%%h-%%p-%%r``。

请注意，如果在 ssh 参数中设置了 -o ControlPath，则会忽略此设置。

配置

  • INI 条目

    [ssh_connection]
control_path = VALUE

  • 环境变量：ANSIBLE_SSH_CONTROL_PATH

  • 变量：ansible_control_path

    在 Ansible 2.7 中添加

control_path_dir

字符串

如果 control path 设置为空，则设置用于 ssh control path 的目录。

此外，还为 control path 设置提供 ``%(directory)s`` 变量。

默认值： "~/.ansible/cp"

配置

  • INI 条目

    [ssh_connection]
control_path_dir = ~/.ansible/cp

  • 环境变量：ANSIBLE_SSH_CONTROL_PATH_DIR

  • 变量：ansible_control_path_dir

    在 Ansible 2.7 中添加

host

字符串

要连接到的主机名/IP。

默认值： "inventory_hostname"

配置

  • 变量：inventory_hostname

  • 变量：ansible_host

  • 变量：ansible_ssh_host

  • 变量：delegated_vars[‘ansible_host’]

  • 变量：delegated_vars[‘ansible_ssh_host’]

host_key_checking

布尔值

确定 SSH 是否应该在检查主机密钥后拒绝连接。

选项

  • false

  • true ← (默认值)

配置

password

字符串

remote_user 的身份验证密码。可以作为 CLI 选项提供。

配置

  • 变量：ansible_password

  • 变量：ansible_ssh_pass

  • 变量：ansible_ssh_password

pipelining

布尔值

流水线技术减少了在远程服务器上执行模块所需的连接操作次数，方法是执行许多 Ansible 模块而无需实际的文件传输。

启用此功能可以显著提高性能。

但是，这可能会与权限提升 (become) 冲突。例如，当使用 sudo 操作时，必须首先在目标主机的 sudoers 文件中禁用 requiretty，这就是此功能默认情况下处于禁用状态的原因。

选项

  • false ← (默认值)

  • true

配置

  • INI 条目

    [defaults]
pipelining = false

    [connection]
pipelining = false

    [ssh_connection]
pipelining = false

  • 环境变量：ANSIBLE_PIPELINING

  • 环境变量：ANSIBLE_SSH_PIPELINING

  • 变量：ansible_pipelining

  • 变量：ansible_ssh_pipelining

pkcs11_provider

字符串

在 ansible-core 2.12 中添加

PKCS11 智能卡提供程序，例如 opensc，示例：/usr/local/lib/opensc-pkcs11.so

需要 sshpass 1.06+ 版本，sshpass 必须支持 -P 选项。

默认值： ""

配置

  • INI 条目

    [ssh_connection]
pkcs11_provider = ""

  • 环境变量：ANSIBLE_PKCS11_PROVIDER

  • 变量：ansible_ssh_pkcs11_provider

port

整数

要连接到的远程端口。

配置

  • INI 条目

    [defaults]
remote_port = VALUE

  • 环境变量：ANSIBLE_REMOTE_PORT

  • 变量：ansible_port

  • 变量：ansible_ssh_port

  • 关键字：port

private_key_file

字符串

要用于身份验证的私钥文件的路径。

配置

  • INI 条目

    [defaults]
private_key_file = VALUE

  • 环境变量：ANSIBLE_PRIVATE_KEY_FILE

  • 变量：ansible_private_key_file

  • 变量：ansible_ssh_private_key_file

  • CLI 参数：–private-key

reconnection_retries

整数

连接尝试次数。

只有当 Ansible 收到返回码为 255 的 SSH 错误时，Ansible 才会重试连接。

返回码非 255 的任何错误都表示程序执行存在问题。

默认值： 0

配置

  • INI 条目

    [connection]
retries = 0

    [ssh_connection]
retries = 0

  • 环境变量：ANSIBLE_SSH_RETRIES

  • 变量：ansible_ssh_retries

    在 Ansible 2.7 中添加

remote_user

字符串

用于登录到远程服务器的用户名，通常由 remote_user 关键字设置。

如果没有提供用户，Ansible 将让 SSH 客户端二进制文件像通常一样选择用户。

配置

  • INI 条目

    [defaults]
remote_user = VALUE

  • 环境变量：ANSIBLE_REMOTE_USER

  • 变量：ansible_user

  • 变量：ansible_ssh_user

  • 关键字：remote_user

  • CLI 参数：–user

scp_executable

字符串

这定义了 scp 二进制文件的位置。它默认为 scp，它将使用 $PATH 中可用的第一个二进制文件。

默认值： "scp"

配置

  • INI 条目

    [ssh_connection]
scp_executable = scp

  • 环境变量：ANSIBLE_SCP_EXECUTABLE

  • 变量：ansible_scp_executable

    在 Ansible 2.7 中添加

scp_extra_args

字符串

专用于 scp CLI 的额外参数

默认值： ""

配置

  • INI 条目

    [ssh_connection]
scp_extra_args = ""

    在 Ansible 2.7 中添加

  • 环境变量：ANSIBLE_SCP_EXTRA_ARGS

    在 Ansible 2.7 中添加

  • 变量：ansible_scp_extra_args

  • CLI 参数：–scp-extra-args

sftp_batch_mode

布尔值

待补充

选项

  • false

  • true ← (默认值)

配置

  • INI 条目

    [ssh_connection]
sftp_batch_mode = true

  • 环境变量：ANSIBLE_SFTP_BATCH_MODE

  • 变量：ansible_sftp_batch_mode

    在 Ansible 2.7 中添加

sftp_executable

字符串

此项定义了 sftp 二进制文件的路径。默认为 sftp，这将使用 $PATH 中第一个可用的二进制文件。

默认值： "sftp"

配置

  • INI 条目

    [ssh_connection]
sftp_executable = sftp

  • 环境变量：ANSIBLE_SFTP_EXECUTABLE

  • 变量：ansible_sftp_executable

    在 Ansible 2.7 中添加

sftp_extra_args

字符串

专用于 sftp 命令行的额外参数。

默认值： ""

配置

  • INI 条目

    [ssh_connection]
sftp_extra_args = ""

    在 Ansible 2.7 中添加

  • 环境变量：ANSIBLE_SFTP_EXTRA_ARGS

    在 Ansible 2.7 中添加

  • 变量：ansible_sftp_extra_args

  • CLI 参数：–sftp-extra-args

ssh_args

字符串

传递给所有 SSH 命令行工具的参数。

默认值： "-C -o ControlMaster=auto -o ControlPersist=60s"

配置

  • INI 条目

    [ssh_connection]
ssh_args = -C -o ControlMaster=auto -o ControlPersist=60s

  • 环境变量：ANSIBLE_SSH_ARGS

  • 变量：ansible_ssh_args

    在 Ansible 2.7 中添加

ssh_common_args

字符串

所有 SSH 命令行工具的常用额外参数。

默认值： ""

配置

  • INI 条目

    [ssh_connection]
ssh_common_args = ""

    在 Ansible 2.7 中添加

  • 环境变量：ANSIBLE_SSH_COMMON_ARGS

    在 Ansible 2.7 中添加

  • 变量：ansible_ssh_common_args

  • CLI 参数：–ssh-common-args

ssh_executable

字符串

此项定义了 SSH 二进制文件的路径。默认为 ssh，这将使用 $PATH 中第一个可用的 SSH 二进制文件。

此选项通常不需要，当系统 SSH 访问受限或使用 SSH 包装器连接到远程主机时，它可能很有用。

默认值： "ssh"

配置

  • INI 条目

    [ssh_connection]
ssh_executable = ssh

  • 环境变量：ANSIBLE_SSH_EXECUTABLE

  • 变量：ansible_ssh_executable

    在 Ansible 2.7 中添加

ssh_extra_args

字符串

专用于 SSH 命令行的额外参数。

默认值： ""

配置

  • INI 条目

    [ssh_connection]
ssh_extra_args = ""

    在 Ansible 2.7 中添加

  • 环境变量：ANSIBLE_SSH_EXTRA_ARGS

    在 Ansible 2.7 中添加

  • 变量：ansible_ssh_extra_args

  • CLI 参数：–ssh-extra-args

ssh_transfer_method

字符串

通过 SSH 传输文件时首选的方法。

选项

  • "piped"：在两端使用 dd 创建 SSH 管道来复制数据。

  • "scp"：在 OpenSSH 中已弃用。对于 OpenSSH >=9.0，您必须添加另一个选项来启用 scp scp_extra_args="-O"。

  • "sftp"：这是使用 SSH 复制内容最可靠的方法。

  • "smart" (默认)：依次尝试每种方法 (sftp > scp > piped)，直到成功或全部失败。

配置

  • INI 条目

    [ssh_connection]
transfer_method = smart

  • 环境变量：ANSIBLE_SSH_TRANSFER_METHOD

  • 变量：ansible_ssh_transfer_method

    在 ansible-core 2.12 中添加

sshpass_prompt

字符串

在 ansible-base 2.10 中添加。

sshpass 应该搜索的密码提示。受 sshpass 1.06 及更高版本支持。

当设置 pkcs11_provider 时，默认为 Enter PIN for。

默认值： ""

配置

  • INI 条目

    [ssh_connection]
sshpass_prompt = ""

  • 环境变量：ANSIBLE_SSHPASS_PROMPT

  • 变量：ansible_sshpass_prompt

timeout

整数

这是建立 SSH 连接时将等待的默认时间。

它还控制建立连接后可以等待多长时间来访问读取连接（在套接字上选择）。

默认值： 10

配置

  • INI 条目

    [defaults]
timeout = 10

    [ssh_connection]
timeout = 10

    在 ansible-core 2.11 中添加。

  • 环境变量：ANSIBLE_TIMEOUT

  • 环境变量：ANSIBLE_SSH_TIMEOUT

    在 ansible-core 2.11 中添加。

  • 变量：ansible_ssh_timeout

    在 ansible-core 2.11 中添加。

  • CLI 参数：–timeout

use_tty

布尔值

将 -tt 添加到 ssh 命令以强制分配 tty。

选项

  • false

  • true ← (默认值)

配置

  • INI 条目

    [ssh_connection]
usetty = true

  • 环境变量：ANSIBLE_SSH_USETTY

  • 变量：ansible_ssh_use_tty

    在 Ansible 2.7 中添加

注释

注意

  • 此插件主要是一个 `ssh` 命令行工具的包装器，选项的确切行为取决于此工具。这意味着此处提供的文档可能会被 CLI 工具本身覆盖。

  • 许多选项在此处默认为 None，但这仅意味着我们不会覆盖 SSH 工具的默认值和/或配置。例如，如果您在此插件中指定端口，它将覆盖 .ssh/config 文件中的任何 Port 条目。

  • ssh 命令行工具使用返回码 255 表示“连接错误”，这可能与也返回 255 作为错误码的命令/工具冲突，并且在此插件中看起来像“不可达”条件或“连接错误”。

作者

  • ansible (@core)

提示

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