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``。

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

配置

  • 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 中添加

主机

字符串

要连接到的主机名/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

整数

连接尝试次数。

Ansible 仅在获取返回代码为 255 的 SSH 错误时才会重试连接。

任何返回代码不为 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

布尔值

TODO: 编写此部分

选择

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

提示

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