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 开始，如果为 null（默认值），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 中添加

主机

字符串

要连接到的主机名/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 ← (默认值)

配置

密码

字符串

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

配置

  • 变量：ansible_password

  • 变量：ansible_ssh_pass

  • 变量：ansible_ssh_password

流水线

布尔值

流水线通过在不实际传输文件的情况下执行许多 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

端口

整数

要连接到的远程端口。

配置

  • INI 条目

    [defaults]
remote_port = VALUE

  • 环境变量：ANSIBLE_REMOTE_PORT

  • 变量：ansible_port

  • 变量：ansible_ssh_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

整数

连接尝试次数。

只有在收到返回代码为 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)

提示

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