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`` 指示在哪里使用控制目录路径设置。

在 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

字符串

如果控制路径设置为空，则此设置将设置要用于 ssh 控制路径的目录。

此外，还为控制路径设置提供 ``%(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 CLI 的额外参数。

默认值： ""

配置

  • 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 CLI 工具的参数。

默认值： "-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 CLI 工具的通用额外参数。

默认值： ""

配置

  • 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 CLI 的额外参数。

默认值： ""

配置

  • 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 实用程序的包装器，选项的确切行为取决于此工具。这意味着此处提供的文档可能会被 CLI 工具本身覆盖。

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

  • ssh CLI 工具使用返回码 255 作为“连接错误”，这可能与也返回 255 作为错误码的命令/工具冲突，并且对该插件看起来像是“无法访问”条件或“连接错误”。

作者

  • ansible (@core)

提示

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