url

Collection Note

This module is part of the ansible.builtin collection. To install the collection, use:

ansible-galaxy collection install ansible.builtin

Added in version 1.9.

Synopsis

• Returns the content of the URL requested to be used as data in play.

Parameters

Parameter	Defaults / Choices	Comments
_terms		urls to query
ca_path string		String of file system path to CA cert bundle to use Env: ANSIBLE_LOOKUP_URL_CA_PATH Version Added: 2.10
ciphers list / elements=string		SSL/TLS Ciphers to use for the request When a list is provided, all ciphers are joined in order with C(:) See the L(OpenSSL Cipher List Format,https://docs.openssl.org/master/man1/openssl-ciphers/#cipher-list-format) for more details. The available ciphers is dependent on the Python and OpenSSL/LibreSSL versions Env: ANSIBLE_LOOKUP_URL_CIPHERS Version Added: 2.14
follow_redirects string	Default: urllib2 Choices: all, no, none, safe, urllib2, yes	Whether or not the URI module should follow redirects. Env: ANSIBLE_LOOKUP_URL_FOLLOW_REDIRECTS Version Added: 2.10
force boolean		Whether or not to set "cache-control" header with value "no-cache" Env: ANSIBLE_LOOKUP_URL_FORCE Version Added: 2.10
force_basic_auth boolean		Force basic authentication Env: ANSIBLE_LOOKUP_URL_FORCE_BASIC_AUTH Version Added: 2.10
headers dictionary		HTTP request headers Version Added: 2.9
http_agent string	Default: ansible-httpget	User-Agent to use in the request. The default was changed in 2.11 to V(ansible-httpget). Env: ANSIBLE_LOOKUP_URL_AGENT Version Added: 2.10
password string		Password to use for HTTP authentication. Version Added: 2.8
split_lines boolean	Default: True	Flag to control if content is returned as a list of lines or as a single text blob
timeout float	Default: 10	How long to wait for the server to send data before giving up Env: ANSIBLE_LOOKUP_URL_TIMEOUT Version Added: 2.10
unix_socket string		String of file system path to unix socket file to use when establishing connection to the provided url Env: ANSIBLE_LOOKUP_URL_UNIX_SOCKET Version Added: 2.10
unredirected_headers list / elements=string		A list of headers to not attach on a redirected request Env: ANSIBLE_LOOKUP_URL_UNREDIR_HEADERS Version Added: 2.10
use_gssapi boolean		Use GSSAPI handler of requests As of Ansible 2.11, GSSAPI credentials can be specified with O(username) and O(password). Env: ANSIBLE_LOOKUP_URL_USE_GSSAPI Version Added: 2.10
use_netrc boolean	Default: True	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 Env: ANSIBLE_LOOKUP_URL_USE_NETRC Version Added: 2.14
use_proxy boolean	Default: True	Flag to control if the lookup will observe HTTP proxy environment variables when present.
username string		Username to use for HTTP authentication. Version Added: 2.8
validate_certs boolean	Default: True	Flag to control SSL certificate validation

Examples

- name: url lookup splits lines by default
  ansible.builtin.debug: msg="{{item}}"
  loop: "{{ lookup('ansible.builtin.url', 'https://github.com/gremlin.keys', wantlist=True) }}"

- name: display ip ranges
  ansible.builtin.debug: msg="{{ lookup('ansible.builtin.url', 'https://ip-ranges.amazonaws.com/ip-ranges.json', split_lines=False) }}"

- name: url lookup using authentication
  ansible.builtin.debug: msg="{{ lookup('ansible.builtin.url', 'https://some.private.site.com/file.txt', username='bob', password='hunter2') }}"

- name: url lookup using basic authentication
  ansible.builtin.debug:
    msg: "{{ lookup('ansible.builtin.url', 'https://some.private.site.com/file.txt', username='bob', password='hunter2', force_basic_auth='True') }}"

- name: url lookup using headers
  ansible.builtin.debug:
    msg: "{{ lookup('ansible.builtin.url', 'https://some.private.site.com/api/service', headers={'header1':'value1', 'header2':'value2'} ) }}"

Return Values

Key	Data Type	Description	Returned
_list	list	list of list of lines or content of url(s)

Authors

• Brian Coca (@bcoca)