Try SpotterDownloads files from HTTP, HTTPS, or FTP to node
| "added in version" 0.6 of ansible.builtin"
Authors: Jan-Piet Mens (@jpmens)
pipInstall with pip install ansible-core==2.16.5
Downloads files from HTTP, HTTPS, or FTP to the remote server. The remote server I(must) have direct access to the remote resource.
By default, if an environment variable C(<protocol>_proxy) is 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 R(setting the environment,playbooks_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 C(--check), it will do a HEAD request to validate the URL but will not download the entire file or verify it against hashes and will report incorrect changed status.
For Windows targets, use the M(ansible.windows.win_get_url) module instead.
- 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 }}'
url:
description:
- HTTP, HTTPS, or FTP URL in the form (http|https|ftp)://[user[:pass]]@host.domain[:port]/path
required: true
type: str
dest:
description:
- Absolute path of where to download the file to.
- If O(dest) is a directory, either the server provided filename or, if none provided,
the base name of the URL on the remote server will be used. If a directory, O(force)
has no effect.
- If O(dest) is a directory, the file will always be downloaded (regardless of the
O(force) and O(checksum) option), but replaced only if the contents changed.
required: true
type: path
mode:
description:
- The permissions the resulting filesystem object should have.
- For those used to I(/usr/bin/chmod) remember that modes are actually octal numbers.
You must give Ansible enough information to parse them correctly. For consistent
results, quote octal numbers (for example, V('644') or V('1777')) so Ansible receives
a string and can do its own conversion from string into number. Adding a leading
zero (for example, V(0755)) works sometimes, but can fail in loops and some other
circumstances.
- Giving Ansible a number without following either of these rules will end up with
a decimal number which will have unexpected results.
- As of Ansible 1.8, the mode may be specified as a symbolic mode (for example, V(u+rwx)
or V(u=rw,g=r,o=r)).
- If O(mode) is not specified and the destination filesystem object B(does not) exist,
the default C(umask) on the system will be used when setting the mode for the newly
created filesystem object.
- If O(mode) is not specified and the destination filesystem object B(does) exist,
the mode of the existing filesystem object will be used.
- Specifying O(mode) is the best way to ensure filesystem objects are created with
the correct permissions. See CVE-2020-1736 for further details.
type: raw
force:
default: false
description:
- If V(true) and O(dest) is not a directory, will download the file every time and
replace the file if the contents change. If V(false), the file will only be downloaded
if the destination does not exist. Generally should be V(true) only for small local
files.
- Prior to 0.6, this module behaved as if V(true) was the default.
type: bool
version_added: '0.7'
version_added_collection: ansible.builtin
group:
description:
- Name of the group that should own the filesystem object, as would be fed to I(chown).
- When left unspecified, it uses the current group of the current user unless you
are root, in which case it can preserve the previous ownership.
type: str
owner:
description:
- Name of the user that should own the filesystem object, as would be fed to I(chown).
- When left unspecified, it uses the current user unless you are root, in which case
it can preserve the previous ownership.
- Specifying a numeric username will be assumed to be a user ID and not a username.
Avoid numeric usernames to avoid this confusion.
type: str
backup:
default: false
description:
- Create a backup file including the timestamp information so you can get the original
file back if you somehow clobbered it incorrectly.
type: bool
version_added: '2.1'
version_added_collection: ansible.builtin
serole:
description:
- The role part of the SELinux filesystem object context.
- When set to V(_default), it will use the C(role) portion of the policy if available.
type: str
setype:
description:
- The type part of the SELinux filesystem object context.
- When set to V(_default), it will use the C(type) portion of the policy if available.
type: str
seuser:
description:
- The user part of the SELinux filesystem object context.
- By default it uses the V(system) policy, where applicable.
- When set to V(_default), it will use the C(user) portion of the policy if available.
type: str
ciphers:
description:
- SSL/TLS Ciphers to use for the request
- When a list is provided, all ciphers are joined in order with V(:)
- See the L(OpenSSL Cipher List Format,https://www.openssl.org/docs/manmaster/man1/openssl-ciphers.html#CIPHER-LIST-FORMAT)
for more details.
- The available ciphers is dependent on the Python and OpenSSL/LibreSSL versions
elements: str
type: list
version_added: '2.14'
version_added_collection: ansible.builtin
headers:
description:
- Add custom HTTP headers to a request in hash/dict format.
- The hash/dict format was added in Ansible 2.6.
- Previous versions used a C("key:value,key:value") string format.
- The C("key:value,key:value") string format is deprecated and has been removed in
version 2.10.
type: dict
version_added: '2.0'
version_added_collection: ansible.builtin
selevel:
description:
- The level part of the SELinux filesystem object context.
- This is the MLS/MCS attribute, sometimes known as the C(range).
- When set to V(_default), it will use the C(level) portion of the policy if available.
type: str
timeout:
default: 10
description:
- Timeout in seconds for URL request.
type: int
version_added: '1.8'
version_added_collection: ansible.builtin
checksum:
default: ''
description:
- 'If a checksum is passed to this parameter, the digest of the destination file will
be calculated after it is downloaded to ensure its integrity and verify that the
transfer completed successfully. Format: <algorithm>:<checksum|url>, e.g. checksum="sha256:D98291AC[...]B6DC7B97",
checksum="sha256:http://example.com/path/sha256sum.txt"'
- If you worry about portability, only the sha1 algorithm is available on all platforms
and python versions.
- The Python ``hashlib`` module is responsible for providing the available algorithms.
The choices vary based on Python version and OpenSSL version.
- On systems running in FIPS compliant mode, the ``md5`` algorithm may be unavailable.
- Additionally, if a checksum is passed to this parameter, and the file exist under
the O(dest) location, the C(destination_checksum) would be calculated, and if checksum
equals C(destination_checksum), the file download would be skipped (unless O(force)
is V(true)). If the checksum does not equal C(destination_checksum), the destination
file is deleted.
type: str
version_added: '2.0'
version_added_collection: ansible.builtin
tmp_dest:
description:
- Absolute path of where temporary file is downloaded to.
- When run on Ansible 2.5 or greater, path defaults to ansible's remote_tmp setting
- When run on Ansible prior to 2.5, it defaults to E(TMPDIR), E(TEMP) or E(TMP) env
variables or a platform specific value.
- U(https://docs.python.org/3/library/tempfile.html#tempfile.tempdir)
type: path
version_added: '2.1'
version_added_collection: ansible.builtin
use_netrc:
default: true
description:
- Determining whether to use credentials from ``~/.netrc`` file
- By default .netrc is used with Basic authentication headers
- When set to False, .netrc credentials are ignored
type: bool
version_added: '2.14'
version_added_collection: ansible.builtin
use_proxy:
default: true
description:
- if V(false), it will not use a proxy, even if one is defined in an environment variable
on the target hosts.
type: bool
attributes:
aliases:
- attr
description:
- The attributes the resulting filesystem object should have.
- To get supported flags look at the man page for I(chattr) on the target system.
- This string should contain the attributes in the same order as the one displayed
by I(lsattr).
- The C(=) operator is assumed as default, otherwise C(+) or C(-) operators need to
be included in the string.
type: str
version_added: '2.3'
version_added_collection: ansible.builtin
client_key:
description:
- PEM formatted file that contains your private key to be used for SSL client authentication.
- If O(client_cert) contains both the certificate and key, this option is not required.
type: path
version_added: '2.4'
version_added_collection: ansible.builtin
decompress:
default: true
description:
- Whether to attempt to decompress gzip content-encoded responses
type: bool
version_added: '2.14'
version_added_collection: ansible.builtin
http_agent:
default: ansible-httpget
description:
- Header to identify as, generally appears in web server logs.
type: str
use_gssapi:
default: false
description:
- Use GSSAPI to perform the authentication, typically this is for Kerberos or Kerberos
through Negotiate authentication.
- Requires the Python library L(gssapi,https://github.com/pythongssapi/python-gssapi)
to be installed.
- Credentials for GSSAPI can be specified with O(url_username)/O(url_password) or
with the GSSAPI env var C(KRB5CCNAME) that specified a custom Kerberos credential
cache.
- NTLM authentication is I(not) supported even if the GSSAPI mech for NTLM has been
installed.
type: bool
version_added: '2.11'
version_added_collection: ansible.builtin
client_cert:
description:
- PEM formatted certificate chain file to be used for SSL client authentication.
- This file can also include the key as well, and if the key is included, O(client_key)
is not required.
type: path
version_added: '2.4'
version_added_collection: ansible.builtin
url_password:
aliases:
- password
description:
- The password for use in HTTP basic authentication.
- If the O(url_username) parameter is not specified, the O(url_password) parameter
will not be used.
- Since version 2.8 you can also use the O(password) alias for this option.
type: str
version_added: '1.6'
version_added_collection: ansible.builtin
url_username:
aliases:
- username
description:
- The username for use in HTTP basic authentication.
- This parameter can be used without O(url_password) for sites that allow empty passwords.
- Since version 2.8 you can also use the O(username) alias for this option.
type: str
version_added: '1.6'
version_added_collection: ansible.builtin
unsafe_writes:
default: false
description:
- Influence when to use atomic operation to prevent data corruption or inconsistent
reads from the target filesystem object.
- By default this module uses atomic operations to prevent data corruption or inconsistent
reads from the target filesystem objects, but sometimes systems are configured or
just broken in ways that prevent this. One example is docker mounted filesystem
objects, which cannot be updated atomically from inside the container and can only
be written in an unsafe manner.
- This option allows Ansible to fall back to unsafe methods of updating filesystem
objects when atomic operations fail (however, it doesn't force Ansible to perform
unsafe writes).
- IMPORTANT! Unsafe writes are subject to race conditions and can lead to data corruption.
type: bool
version_added: '2.2'
version_added_collection: ansible.builtin
validate_certs:
default: true
description:
- If V(false), SSL certificates will not be validated.
- This should only be used on personally controlled sites using self-signed certificates.
type: bool
force_basic_auth:
default: false
description:
- Force the sending of the Basic authentication header upon initial request.
- httplib2, the library used by the uri module only sends authentication information
when a webservice responds to an initial request with a 401 status. Since some basic
auth services do not properly send a 401, logins will fail.
type: bool
version_added: '2.0'
version_added_collection: ansible.builtin
unredirected_headers:
default: []
description:
- A list of header names that will not be sent on subsequent redirected requests.
This list is case insensitive. By default all headers will be redirected. In some
cases it may be beneficial to list headers such as C(Authorization) here to avoid
potential credential exposure.
elements: str
type: list
version_added: '2.12'
version_added_collection: ansible.builtin
backup_file: description: name of backup file created after download returned: changed and if backup=yes sample: /path/to/file.txt.2015-02-12@22:09~ type: str checksum_dest: description: sha1 checksum of the file after copy returned: success sample: 6e642bb8dd5c2e027bf21dd923337cbb4214f827 type: str checksum_src: description: sha1 checksum of the file returned: success sample: 6e642bb8dd5c2e027bf21dd923337cbb4214f827 type: str dest: description: destination file/path returned: success sample: /path/to/file.txt type: str elapsed: description: The number of seconds that elapsed while performing the download returned: always sample: 23 type: int gid: description: group id of the file returned: success sample: 100 type: int group: description: group of the file returned: success sample: httpd type: str md5sum: description: md5 checksum of the file after download returned: when supported sample: 2a5aeecc61dc98c4d780b14b330e3282 type: str mode: description: permissions of the target returned: success sample: '0644' type: str msg: description: the HTTP message from the request returned: always sample: OK (unknown bytes) type: str owner: description: owner of the file returned: success sample: httpd type: str secontext: description: the SELinux security context of the file returned: success sample: unconfined_u:object_r:user_tmp_t:s0 type: str size: description: size of the target returned: success sample: 1220 type: int src: description: source file used after download returned: always sample: /tmp/tmpAdFLdV type: str state: description: state of the target returned: success sample: file type: str status_code: description: the HTTP status code from the request returned: always sample: 200 type: int uid: description: owner id of the file, after execution returned: success sample: 100 type: int url: description: the actual URL used for the request returned: always sample: https://www.ansible.com/ type: str