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 字符串	结果文件系统对象应该具有的属性。 要获取支持的标志，请查看目标系统上的 chattr 手册页。 此字符串应按 lsattr 显示的顺序包含属性。 = 运算符被认为是默认运算符，否则需要在字符串中包含 + 或 - 运算符。
备份 布尔值	创建备份文件，其中包含时间戳信息，以便您在错误地覆盖文件后恢复原始文件。 选择 false ← (default) 真的
校验和 字符串	如果将校验和传递给此参数，则将在下载目标文件后计算其摘要，以确保其完整性并验证传输是否成功完成。 格式：<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 下载校验和文件。 默认： ""
密码 列表 / 元素=字符串 添加到 ansible-core 2.14	要用于请求的 SSL/TLS 密码。 提供列表时，所有密码都将按顺序用 : 连接。 有关更多详细信息，请参见 OpenSSL 密码列表格式。 可用的密码取决于 Python 和 OpenSSL/LibreSSL 版本。
client_cert 路径	要用于 SSL 客户端身份验证的 PEM 格式证书链文件。 此文件还可以包含密钥，如果包含密钥，则不需要 client_key。
client_key 路径	包含用于 SSL 客户端身份验证的私钥的 PEM 格式文件。 如果 client_cert 包含证书和密钥，则不需要此选项。
解压缩 布尔值 添加到 ansible-core 2.14	是否尝试解压缩 gzip 内容编码的响应。 选择 错误的 true ← (default)
dest 路径 / 必需	下载文件到的绝对路径。 如果 dest 是目录，则使用服务器提供的文件名，或者如果未提供文件名，则使用远程服务器上的 URL 的基本名称。 如果是目录，则 force 无效。 如果 dest 是目录，则始终下载文件（无论 force 和 checksum 选项如何），但仅在内容更改时才替换。
强制 布尔值	如果 true 并且 dest 不是目录，则每次都下载文件，如果内容更改，则替换文件。 如果 false，则仅在目标不存在时下载文件。 通常，仅对小型本地文件使用 true。 在 0.6 之前，此模块的行为类似于 true 是默认值。 选择 false ← (default) 真的
force_basic_auth 布尔值	强制在初始请求时发送基本身份验证标头。 uri 模块使用的库 httplib2 仅在 Web 服务以 401 状态响应初始请求时才发送身份验证信息。 由于某些基本身份验证服务无法正确发送 401，因此登录将失败。 选择 false ← (default) 真的
组 字符串	应拥有文件系统对象的组的名称，如将馈送到 chown。 如果未指定，它将使用当前用户的当前组，除非您是 root 用户，在这种情况下它可以保留之前的拥有权。
headers dictionary	以哈希/字典格式将自定义 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 ← (default) 真的
url string / required	以 (http|https|ftp://[user[:pass]]@host.domain[:port]/path) 格式表示的 HTTP、HTTPS 或 FTP URL。
url_password aliases: password 字符串	用于 HTTP 基本身份验证的密码。 如果未指定 url_username 参数，则不会使用 url_password 参数。 从版本 2.8 开始，您还可以使用 password 别名来表示此选项。
url_username aliases: username 字符串	用于 HTTP 基本身份验证的用户名。 此参数可以在没有 url_password 的情况下使用，适用于允许空密码的站点。 从版本 2.8 开始，您还可以使用 username 别名来表示此选项。
use_gssapi 布尔值 在 ansible-core 2.11 中添加	使用 GSSAPI 执行身份验证，通常是针对 Kerberos 或通过 Negotiate 身份验证的 Kerberos。 需要安装 Python 库 gssapi。 GSSAPI 的凭据可以使用 url_username/url_password 或使用指定自定义 Kerberos 凭据缓存的 GSSAPI 环境变量 KRB5CCNAME 来指定。 即使安装了 NTLM 的 GSSAPI 机制，也不支持 NTLM 身份验证。 选择 false ← (default) 真的
use_netrc 布尔值 添加到 ansible-core 2.14	确定是否使用来自 ~/.netrc 文件的凭据。 默认情况下，.netrc 与基本身份验证标头一起使用。 如果设置为 false，则忽略 .netrc 凭据。 选择 错误的 true ← (default)
use_proxy 布尔值	如果设置为 false，它将不使用代理，即使目标主机上的环境变量中定义了代理。 选择 错误的 true ← (default)
validate_certs 布尔值	如果设置为 false，则不会验证 SSL 证书。 这应该只在使用自签名证书的个人控制的站点上使用。 选择 错误的 true ← (default)

属性

属性	支持	描述
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 字符串	下载后创建的备份文件名称 返回： changed 和 if 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
组 字符串	文件的组 返回： success 示例： "httpd"
md5sum 字符串	下载后文件的 md5 校验和 返回： 当支持时 示例： "2a5aeecc61dc98c4d780b14b330e3282"
mode 字符串	目标的权限 返回： success 示例： "0644"
msg 字符串	来自请求的 HTTP 消息 返回： 始终 示例： "OK (unknown bytes)"
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://www.ansible.org.cn/"

作者

• Jan-Piet Mens (@jpmens)

集合链接

• 问题追踪器
• 仓库（源代码）
• 通讯