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

字符串

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

此外，为 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 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"：创建 SSH 管道，两侧都使用 dd 来复制数据。

  • "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)

提示

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