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

注意

此模块是 ansible-core 的一部分，包含在所有 Ansible 安装中。在大多数情况下，即使不指定集合关键字，您也可以使用简短的模块名称 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 字符串	生成的 filesystem 对象应具有的属性。 要获取支持的标志，请查看目标系统上 chattr 的手册页。 此字符串应包含与 lsattr 显示的顺序相同的属性。 = 运算符被假定为默认运算符，否则需要在字符串中包含 + 或 - 运算符。
backup 布尔值	创建一个包含时间戳信息的备份文件，以便在您以某种方式错误地覆盖它时可以取回原始文件。 选项 false ← (默认) true
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 字符串	应该拥有 filesystem 对象的组的名称，就像将传递给 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://[user[:pass]]@host.domain[:port]/path) 的 HTTP、HTTPS 或 FTP URL。
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 或通过协商身份验证的 Kerberos。 需要安装 Python 库 gssapi。 可以使用 url_username/url_password 或 GSSAPI 环境变量 KRB5CCNAME 指定用于 GSSAPI 的凭据，该变量指定了自定义的 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	支持： 部分 changed 状态将反映与空源文件的比较	可以在 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 字符串	下载后创建的备份文件的名称 返回： changed 以及如果 backup=yes 示例： "/path/to/file.txt.2015-02-12@22:09~"
checksum_dest 字符串	复制后文件的 sha1 校验和 返回： success 示例： "6e642bb8dd5c2e027bf21dd923337cbb4214f827"
checksum_src 字符串	文件的 sha1 校验和 返回： success 示例： "6e642bb8dd5c2e027bf21dd923337cbb4214f827"
dest 字符串	目标文件/路径 返回： success 示例： "/path/to/file.txt"
elapsed integer	执行下载所经过的秒数 返回： 总是 示例： 23
gid integer	文件的组 ID 返回： success 示例： 100
group 字符串	文件的组 返回： success 示例： "httpd"
md5sum 字符串	下载后文件的 MD5 校验和 返回： 如果支持 示例： "2a5aeecc61dc98c4d780b14b330e3282"
mode 字符串	目标的权限 返回： success 示例： "0644"
msg 字符串	来自请求的 HTTP 消息 返回： 总是 示例： "OK (未知字节数)"
owner 字符串	文件的所有者 返回： success 示例： "httpd"
secontext 字符串	文件的 SELinux 安全上下文 返回： success 示例： "unconfined_u:object_r:user_tmp_t:s0"
size integer	目标的大小 返回： success 示例： 1220
src 字符串	下载后使用的源文件 返回： 总是 示例： "/tmp/tmpAdFLdV"
state 字符串	目标的状态 返回： success 示例： "file"
status_code integer	来自请求的 HTTP 状态码 返回： 总是 示例： 200
uid integer	执行后文件的所有者 ID 返回： success 示例： 100
url 字符串	用于请求的实际 URL 返回： 总是 示例： "https://ansible.org.cn/"

作者

• Jan-Piet Mens (@jpmens)

集合链接

• 问题跟踪器
• 存储库 (源代码)
• 通信