ansible.builtin.get_url 模块 – 从 HTTP、HTTPS 或 FTP 下载文件到节点

注意

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

概要

• 从 HTTP、HTTPS 或 FTP 下载文件到远程服务器。远程服务器 *必须* 能直接访问远程资源。

• 默认情况下，如果目标主机上设置了环境变量 <protocol>_proxy，请求将通过该代理发送。此行为可以通过为该任务设置变量（参见 设置环境）或使用 use_proxy 选项来覆盖。

• HTTP 重定向可以从 HTTP 重定向到 HTTPS，因此您应该确保两种协议的代理环境都正确。

• 从 Ansible 2.4 开始，当与 --check 一起运行时，它将执行 HEAD 请求以验证 URL，但不会下载整个文件或根据哈希值对其进行验证，并将报告不正确的已更改状态。

• 对于 Windows 目标，请使用 ansible.windows.win_get_url 模块代替。

参数

参数	注释
attributes 别名：attr 字符串	结果文件系统对象应具有的属性。 要获取支持的标志，请查看目标系统上的 chattr 手册页。 此字符串应包含与 lsattr 显示的顺序相同的属性。 = 运算符被认为是默认运算符，否则需要在字符串中包含 + 或 - 运算符。
backup 布尔值	创建一个备份文件，其中包含时间戳信息，以便您可以恢复原始文件，以防您错误地将其覆盖。 选项 false ← (默认) true
checksum 字符串	如果将校验和传递到此参数，则将在下载目标文件后计算其摘要以确保其完整性并验证传输是否成功完成。格式：<algorithm>:<checksum|url>，例如 checksum="sha256:D98291AC[...]B6DC7B97", C(checksum="sha256:http://example.com/path/sha256sum.txt"。 如果您担心可移植性，则只有 sha1 算法在所有平台和 python 版本上可用。 Python hashlib 模块负责提供可用的算法。选择根据 Python 版本和 OpenSSL 版本而有所不同。 在以 FIPS 合规模式运行的系统上，md5 算法可能不可用。 此外，如果将校验和传递到此参数，并且该文件存在于 dest 位置，则将计算 destination_checksum，如果校验和等于 destination_checksum，则将跳过文件下载（除非 force=true）。如果校验和不等于 destination_checksum，则删除目标文件。 如果校验和 URL 需要用户名和密码，则使用 url_username 和 url_password 下载校验和文件。 默认： ""
ciphers 列表 / 元素=字符串 在 ansible-core 2.14 中添加	用于请求的 SSL/TLS 密码。 当提供列表时，所有密码将按顺序用 : 连接。 有关更多详细信息，请参见 OpenSSL 密码列表格式。 可用的密码取决于 Python 和 OpenSSL/LibreSSL 版本。
client_cert 路径	用于 SSL 客户端身份验证的 PEM 格式证书链文件。 此文件还可以包含密钥，如果包含密钥，则不需要 client_key。
client_key 路径	包含用于 SSL 客户端身份验证的私钥的 PEM 格式文件。 如果 client_cert 包含证书和密钥，则不需要此选项。
decompress 布尔值 在 ansible-core 2.14 中添加	是否尝试解压缩 gzip 编码的响应。 选项 false true ← (默认)
dest 路径 / 必需	下载文件的绝对路径。 如果 dest 是目录，则使用服务器提供的文件名或（如果没有提供）远程服务器上的 URL 的基本名称。如果为目录，则 force 无效。 如果 dest 是目录，则始终下载文件（无论 force 和 checksum 选项如何），但仅在内容更改时替换。
force 布尔值	如果 true 且 dest 不是目录，则每次都会下载文件，并在内容更改时替换文件。如果 false，则仅在目标不存在时下载文件。通常，仅对于小的本地文件，应为 true。 在 0.6 之前，此模块的行为类似于 true 是默认值。 选项 false ← (默认) true
force_basic_auth 布尔值	强制在初始请求时发送基本身份验证标头。 uri 模块使用的库 httplib2 仅在 Web 服务对初始请求以 401 状态响应时发送身份验证信息。由于某些基本身份验证服务无法正确发送 401，因此登录将失败。 选项 false ← (默认) true
group 字符串	应拥有文件系统对象的组的名称，如将传递给 chown 一样。 如果未指定，它将使用当前用户的当前组，除非您是 root 用户，在这种情况下，它可以保留先前的所有权。
headers 字典	以哈希/字典格式向请求添加自定义 HTTP 标头。 哈希/字典格式是在 Ansible 2.6 中添加的。 以前的版本使用 "key:value,key:value" 字符串格式。 "key:value,key:value" 字符串格式已弃用，并在版本 2.10 中删除。
http_agent 字符串	标识为的标头，通常出现在 Web 服务器日志中。 默认值: "ansible-httpget"
mode any	生成的的文件系统对象应该具有的权限。 对于那些习惯使用 /usr/bin/chmod 的人来说，请记住模式实际上是八进制数。您必须向 Ansible 提供足够的 信息来正确解析它们。为了获得一致的结果，请引用八进制数（例如，'644' 或 '1777'），这样 Ansible 就会收到一个字符串，并可以将字符串转换为数字。 添加前导零（例如，0755）有时有效，但在循环和其他一些情况下可能会 失败。 如果向 Ansible 提供一个不遵循上述任何规则的数字，最终将得到一个十进制数，这将导致意外的结果。 从 Ansible 1.8 开始，模式可以指定为符号模式（例如，u+rwx 或 u=rw,g=r,o=r）。 如果未指定 mode 并且目标文件系统对象 *不存在*，则在设置新创建的文件系统 对象的模式时将使用系统上的默认 umask。 如果未指定 mode 并且目标文件系统对象 *存在*，则将使用现有文件系统对象的模式。 指定 mode 是确保以正确权限创建文件系统对象的最佳 方式。有关更多详细信息，请参阅 CVE-2020-1736。
owner 字符串	应拥有文件系统对象的用户的名称，与提供给 chown 的名称相同。 如果未指定，它将使用当前用户，除非您是 root 用户，在这种情况下，它可以保留之前的 所有权。 指定数字用户名将被视为用户 ID，而不是用户名。为了避免混淆，请避免使用数字 用户名。
selevel 字符串	SELinux 文件系统对象上下文的级别部分。 这是 MLS/MCS 属性，有时称为 range。 设置为 _default 时，它将使用策略的 level 部分（如果可用）。
serole 字符串	SELinux 文件系统对象上下文的角色部分。 设置为 _default 时，它将使用策略的 role 部分（如果可用）。
setype 字符串	SELinux 文件系统对象上下文的类型部分。 设置为 _default 时，它将使用策略的 type 部分（如果可用）。
seuser 字符串	SELinux 文件系统对象上下文的用户部分。 默认情况下，它使用 system 策略（如果适用）。 设置为 _default 时，它将使用策略的 user 部分（如果可用）。
timeout integer	URL 请求的超时时间（秒）。 默认值: 10
tmp_dest 路径	下载临时文件的绝对路径。 在 Ansible 2.5 或更高版本上运行时，路径默认为 Ansible 的 remote_tmp 设置。 在 Ansible 2.5 之前的版本上运行时，它默认为 TMPDIR、TEMP 或 TMP 环境变量，或特定于平台的值。 https://docs.pythonlang.cn/3/library/tempfile.html#tempfile.tempdir.
unredirected_headers 列表 / 元素=字符串 在 ansible-core 2.12 中添加	不会在后续重定向请求中发送的标头名称列表。此列表不区分大小写。默认情况下，所有标头都将被重定向。在某些情况下，将诸如 Authorization 之类的标头列入此处可能会有利，以避免潜在的凭据泄露。 默认值: []
unsafe_writes 布尔值	影响何时使用原子操作来防止数据损坏或从目标文件系统对象进行不一致的读取。 默认情况下，此模块使用原子操作来防止数据损坏或从目标文件系统对象进行不一致的读取，但有时系统以阻止此操作的方式进行配置或只是出现了故障。一个例子是 docker 挂载的文件系统对象，它们不能在容器内进行原子更新，只能以不安全的方式写入。 此选项允许 Ansible 在原子操作失败时回退到不安全的文件系统对象更新方法（但是，它不会强制 Ansible 执行不安全的写入）。 重要！不安全的写入会受到竞争条件的影响，并可能导致数据损坏。 选项 false ← (默认) true
url string / required	HTTP、HTTPS 或 FTP URL，格式为 (http|https|ftp://[user[:pass]]@host.domain[:port]/path)。
url_password 别名: password 字符串	用于 HTTP 基本身份验证的密码。 如果未指定 url_username 参数，则不会使用 url_password 参数。 从 2.8 版本开始，您还可以对该选项使用 password 别名。
url_username 别名: username 字符串	用于 HTTP 基本身份验证的用户名。 此参数可以在没有 url_password 的情况下使用，适用于允许使用空密码的站点。 从 2.8 版本开始，您还可以对该选项使用 username 别名。
use_gssapi 布尔值 在 ansible-core 2.11 中添加	使用 GSSAPI 执行身份验证，通常用于 Kerberos 或通过 Negotiate 身份验证的 Kerberos。 要求安装 Python 库 gssapi。 GSSAPI 的凭据可以使用 url_username/url_password 或 GSSAPI 环境变量 KRB5CCNAME 指定，该变量指定自定义 Kerberos 凭据缓存。 即使安装了 NTLM 的 GSSAPI 机制，也不支持 NTLM 身份验证。 选项 false ← (默认) true
use_netrc 布尔值 在 ansible-core 2.14 中添加	确定是否使用来自 ~/.netrc 文件的凭据。 默认情况下，.netrc 与基本身份验证标头一起使用。 当设置为 false 时，将忽略 .netrc 凭据。 选项 false true ← (默认)
use_proxy 布尔值	如果设置为 false，即使在目标主机上定义了代理，也不会使用代理。 选项 false true ← (默认)
validate_certs 布尔值	如果设置为 false，则不会验证 SSL 证书。 这仅应在使用自签名证书的个人控制的站点上使用。 选项 false true ← (默认)

属性

属性	支持	描述
check_mode	支持: 部分 更改状态将反映与空源文件的比较	可以在 check_mode 中运行并返回更改状态预测，而无需修改目标，如果不受支持，则将跳过操作。
diff_mode	支持: 无	在 diff 模式下，将返回有关更改内容（或在 check_mode 中可能需要更改的内容）的详细信息
platform	平台: posix	可以对其进行操作的目标操作系统/系列

备注

注意

• 对于 Windows 目标，请使用 ansible.windows.win_get_url 模块代替。

另请参阅

另请参阅

ansible.builtin.uri

与 Web 服务交互。

ansible.windows.win_get_url

有关 ansible.windows.win_get_url 模块的官方文档。

示例

- name: Download foo.conf
  ansible.builtin.get_url:
    url: http://example.com/path/file.conf
    dest: /etc/foo.conf
    mode: '0440'

- name: Download file and force basic auth
  ansible.builtin.get_url:
    url: http://example.com/path/file.conf
    dest: /etc/foo.conf
    force_basic_auth: yes

- name: Download file with custom HTTP headers
  ansible.builtin.get_url:
    url: http://example.com/path/file.conf
    dest: /etc/foo.conf
    headers:
      key1: one
      key2: two

- name: Download file with check (sha256)
  ansible.builtin.get_url:
    url: http://example.com/path/file.conf
    dest: /etc/foo.conf
    checksum: sha256:b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c

- name: Download file with check (md5)
  ansible.builtin.get_url:
    url: http://example.com/path/file.conf
    dest: /etc/foo.conf
    checksum: md5:66dffb5228a211e61d6d7ef4a86f5758

- name: Download file with checksum url (sha256)
  ansible.builtin.get_url:
    url: http://example.com/path/file.conf
    dest: /etc/foo.conf
    checksum: sha256:http://example.com/path/sha256sum.txt

- name: Download file from a file path
  ansible.builtin.get_url:
    url: file:///tmp/a_file.txt
    dest: /tmp/afilecopy.txt

- name: < Fetch file that requires authentication.
        username/password only available since 2.8, in older versions you need to use url_username/url_password
  ansible.builtin.get_url:
    url: http://example.com/path/file.conf
    dest: /etc/foo.conf
    username: bar
    password: '{{ mysecret }}'

返回值

常见的返回值在 此处进行了介绍，以下是此模块独有的字段

键	描述
backup_file 字符串	下载后创建的备份文件的名称 返回: 更改，如果 backup=yes 示例: "/path/to/file.txt.2015-02-12@22:09~"
checksum_dest 字符串	复制后文件的 sha1 校验和 返回: 成功 示例: "6e642bb8dd5c2e027bf21dd923337cbb4214f827"
checksum_src 字符串	文件的 sha1 校验和 返回: 成功 示例: "6e642bb8dd5c2e027bf21dd923337cbb4214f827"
dest 字符串	目标文件/路径 返回: 成功 示例: "/path/to/file.txt"
elapsed integer	执行下载期间经过的秒数 返回: 始终 示例: 23
gid integer	文件的组 ID 返回: 成功 示例: 100
group 字符串	文件的组 返回: 成功 示例： "httpd"
md5sum 字符串	下载后文件的 md5 校验和 返回： 支持时 示例： "2a5aeecc61dc98c4d780b14b330e3282"
mode 字符串	目标的权限 返回: 成功 示例： "0644"
msg 字符串	来自请求的 HTTP 消息 返回: 始终 示例： "OK (unknown bytes)"
owner 字符串	文件的拥有者 返回: 成功 示例： "httpd"
secontext 字符串	文件的 SELinux 安全上下文 返回: 成功 示例： "unconfined_u:object_r:user_tmp_t:s0"
size integer	目标的大小 返回: 成功 示例： 1220
src 字符串	下载后使用的源文件 返回: 始终 示例： "/tmp/tmpAdFLdV"
state 字符串	目标的状态 返回: 成功 示例： "file"
status_code integer	来自请求的 HTTP 状态码 返回: 始终 示例： 200
uid integer	文件的所有者 ID，执行后 返回: 成功 示例: 100
url 字符串	请求使用的实际 URL 返回: 始终 示例： "https://www.ansible.org.cn/"

作者

• Jan-Piet Mens (@jpmens)

集合链接

• 问题跟踪器
• 仓库（源代码）
• 通信