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 布尔值	强制在初始请求时发送 Basic 身份验证标头。 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 任意	结果文件系统对象应具有的权限。 对于习惯使用/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 整数	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 字符串 / 必需	形式为(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或指定自定义 Kerberos 凭据缓存的 GSSAPI 环境变量KRB5CCNAME来指定 GSSAPI 的凭据。 即使安装了 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	支持：不支持	在差异模式下，将返回有关已更改内容（或可能需要在 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 整数	执行下载所花费的秒数 返回值： 始终返回 示例： 23
gid 整数	文件的组 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 整数	目标文件的大小 返回：成功 示例： 1220
src 字符串	下载后使用的源文件 返回值： 始终返回 示例： "/tmp/tmpAdFLdV"
state 字符串	目标文件的状态 返回：成功 示例： "file"
status_code 整数	请求的 HTTP 状态码 返回值： 始终返回 示例： 200
uid 整数	执行后文件的拥有者 ID 返回：成功 示例： 100
url 字符串	请求实际使用的 URL 返回值： 始终返回 示例： "https://ansible.org.cn/"

作者

• Jan-Piet Mens (@jpmens)

资源链接

• 问题追踪器
• 代码仓库
• 通信