ansible.builtin.get_url – Downloads files from HTTP, HTTPS, or FTP to node¶
Note
This module is part of ansible-base and included in all Ansible
installations. In most cases, you can use the short module name
get_url even without specifying the collections: keyword.
Despite that, we recommend you use the FQCN for easy linking to the module
documentation and to avoid conflicting with other collections that may have
the same module name.
New in version 0.6: of ansible.builtin
Synopsis¶
Downloads files from HTTP, HTTPS, or FTP to the remote server. The remote server must have direct access to the remote resource.
By default, if an environment variable
<protocol>_proxyis set on the target host, requests will be sent through that proxy. This behaviour can be overridden by setting a variable for this task (see setting the environment), or by using the use_proxy option.HTTP redirects can redirect from HTTP to HTTPS so you should be sure that your proxy environment for both protocols is correct.
From Ansible 2.4 when run with
--check, it will do a HEAD request to validate the URL but will not download the entire file or verify it against hashes.For Windows targets, use the ansible.windows.win_get_url module instead.
Parameters¶
Notes¶
Note
For Windows targets, use the ansible.windows.win_get_url module instead.
See Also¶
See also
- ansible.builtin.uri
The official documentation on the ansible.builtin.uri module.
- ansible.windows.win_get_url
The official documentation on the ansible.windows.win_get_url module.
Examples¶
- name: Download foo.conf
get_url:
url: http://example.com/path/file.conf
dest: /etc/foo.conf
mode: '0440'
- name: Download file and force basic auth
get_url:
url: http://example.com/path/file.conf
dest: /etc/foo.conf
force_basic_auth: yes
- name: Download file with custom HTTP headers
get_url:
url: http://example.com/path/file.conf
dest: /etc/foo.conf
headers:
key1: one
key2: two
- name: Download file with check (sha256)
get_url:
url: http://example.com/path/file.conf
dest: /etc/foo.conf
checksum: sha256:b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c
- name: Download file with check (md5)
get_url:
url: http://example.com/path/file.conf
dest: /etc/foo.conf
checksum: md5:66dffb5228a211e61d6d7ef4a86f5758
- name: Download file with checksum url (sha256)
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
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
get_url:
url: http://example.com/path/file.conf
dest: /etc/foo.conf
username: bar
password: '{{ mysecret }}'
Return Values¶
Common return values are documented here, the following are the fields unique to this module:
| Key | Returned | Description |
|---|---|---|
|
backup_file
string
|
changed and if backup=yes |
name of backup file created after download
Sample:
/path/to/[email protected]:09~
|
|
checksum_dest
string
|
success |
sha1 checksum of the file after copy
Sample:
6e642bb8dd5c2e027bf21dd923337cbb4214f827
|
|
checksum_src
string
|
success |
sha1 checksum of the file
Sample:
6e642bb8dd5c2e027bf21dd923337cbb4214f827
|
|
dest
string
|
success |
destination file/path
Sample:
/path/to/file.txt
|
|
elapsed
integer
|
always |
The number of seconds that elapsed while performing the download
Sample:
23
|
|
gid
integer
|
success |
group id of the file
Sample:
100
|
|
group
string
|
success |
group of the file
Sample:
httpd
|
|
md5sum
string
|
when supported |
md5 checksum of the file after download
Sample:
2a5aeecc61dc98c4d780b14b330e3282
|
|
mode
string
|
success |
permissions of the target
Sample:
0644
|
|
msg
string
|
always |
the HTTP message from the request
Sample:
OK (unknown bytes)
|
|
owner
string
|
success |
owner of the file
Sample:
httpd
|
|
secontext
string
|
success |
the SELinux security context of the file
Sample:
unconfined_u:object_r:user_tmp_t:s0
|
|
size
integer
|
success |
size of the target
Sample:
1220
|
|
src
string
|
always |
source file used after download
Sample:
/tmp/tmpAdFLdV
|
|
state
string
|
success |
state of the target
Sample:
file
|
|
status_code
integer
|
always |
the HTTP status code from the request
Sample:
200
|
|
uid
integer
|
success |
owner id of the file, after execution
Sample:
100
|
|
url
string
|
always |
the actual URL used for the request
Sample:
https://www.ansible.com/
|
Authors¶
Jan-Piet Mens (@jpmens)