通过 URL 下载文件
ansible.builtin.get_url 可以通过 URL 下载文件。
| 选项名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
attributes |
str |
null | 设置文件系统对象的属性，格式参考 lsattr；支持 +, -, = 操作符。别名：attr。 |
backup |
bool |
false |
创建目标文件的备份副本（带时间戳）。 |
checksum |
str |
'' |
提供格式为 <算法>:<值> 的校验和，如 sha256:abcd1234...，用于校验完整性并决定是否跳过下载。 |
ciphers |
list |
null | 指定 SSL/TLS 加密套件，多个套件以 : 连接。 |
client_cert |
path |
null | PEM 格式的客户端证书，可包含私钥。 |
client_key |
path |
null | 客户端私钥 PEM 文件；若 client_cert 已包含，则可省略。 |
decompress |
bool |
true |
自动解压 gzip 编码响应内容。 |
dest |
path |
--- | 下载文件保存的目标路径（必须）。若为目录，会使用服务器提供的文件名。 |
force |
bool |
false |
是否强制下载（即使目标文件存在）。只在 dest 是文件时有效。 |
force_basic_auth |
bool |
false |
是否强制初次请求就发送 Basic Auth 头信息（用于兼容不返回 401 的服务）。 |
group |
str |
null | 目标文件所属的组名。默认继承当前用户组。 |
headers |
dict |
null | 自定义 HTTP 请求头，格式为字典。 |
http_agent |
str |
ansible-httpget |
请求时发送的 User-Agent 标识。 |
mode |
raw |
null | 文件权限，如 0644、u=rw,g=r,o=r。建议使用字符串格式以避免意外。 |
owner |
str |
null | 目标文件所属用户名。默认为当前用户。 |
selevel |
str |
null | SELinux 上下文的 level 部分。 |
serole |
str |
null | SELinux 上下文的 role 部分。 |
setype |
str |
null | SELinux 上下文的 type 部分。 |
seuser |
str |
null | SELinux 上下文的 user 部分。 |
timeout |
int |
10 |
URL 请求超时时间（秒）。 |
tmp_dest |
path |
null | 下载临时文件的目录，默认 ~/.ansible/tmp/，可以通过 remote_tmp 在配置文件设置默认位置。 |
unredirected_headers |
list |
[] |
不跟随重定向的 HTTP 头名称列表，适用于防止认证信息泄露。 |
unsafe_writes |
bool |
false |
是否允许非原子写操作（如 Docker 下）。有数据一致性风险。 |
url |
str |
--- | 下载的 URL，支持 http、https 和 ftp。 |
url_password |
str |
null | HTTP 基本认证密码。别名：password。 |
url_username |
str |
null | HTTP 基本认证用户名。别名：username。 |
use_gssapi |
bool |
false |
是否使用 GSSAPI（Kerberos）进行认证。需要安装 gssapi Python 库。 |
use_netrc |
bool |
true |
是否使用 ~/.netrc 中的凭据。 |
use_proxy |
bool |
true |
是否使用环境变量中的代理配置。 |
validate_certs |
bool |
true |
是否校验 HTTPS 证书，设为 false 可跳过验证（如自签名证书）。 |
常用选项：
| 选项名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
backup |
bool |
false |
创建目标文件的备份副本（带时间戳）。 |
checksum |
str |
'' |
提供格式为 <算法>:<值> 的校验和，如 sha256:abcd1234...，用于校验完整性并决定是否跳过下载。 |
dest |
path |
--- | 下载文件保存的目标路径（必须）。若为目录，会使用服务器提供的文件名。 |
force |
bool |
false |
是否强制下载（即使目标文件存在）。只在 dest 是文件时有效。 |
force_basic_auth |
bool |
false |
是否强制初次请求就发送 Basic Auth 头信息（用于兼容不返回 401 的服务）。 |
group |
str |
null | 目标文件所属的组名。默认继承当前用户组。 |
headers |
dict |
null | 自定义 HTTP 请求头，格式为字典。 |
http_agent |
str |
ansible-httpget |
请求时发送的 User-Agent 标识。 |
mode |
raw |
null | 文件权限，如 0644、u=rw,g=r,o=r。建议使用字符串格式以避免意外。 |
owner |
str |
null | 目标文件所属用户名。默认为当前用户。 |
timeout |
int |
10 |
URL 请求超时时间（秒）。 |
unredirected_headers |
list |
[] |
不跟随重定向的 HTTP 头名称列表，适用于防止认证信息泄露。 |
url |
str |
--- | 下载的 URL，支持 http、https 和 ftp。 |
url_password |
str |
null | HTTP 基本认证密码。别名：password。 |
url_username |
str |
null | HTTP 基本认证用户名。别名：username。 |
use_proxy |
bool |
true |
是否使用环境变量中的代理配置。 |
validate_certs |
bool |
true |
是否校验 HTTPS 证书，设为 false 可跳过验证（如自签名证书）。 |
- 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/afile.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 }}'