usable_range

Collection Note

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

ansible-galaxy collection install ansible.utils

Added in version 2.3.0.

Synopsis

• For a given IP address (IPv4 or IPv6) in CIDR form, the plugin generates a list of usable IP addresses belonging to the network.

Parameters

Parameter	Defaults / Choices	Comments
ip str required		A string that represents an IP address of network in CIDR form For example: C(10.0.0.0/24) or C(2001:db8:abcd:0012::0/124)

Examples

#### Simple examples

- name: Expand and produce list of usable IP addresses in 10.0.0.0/28
  ansible.builtin.set_fact:
    data: "{{ '10.0.0.0/28' | ansible.utils.usable_range }}"

# TASK [Expand and produce list of usable IP addresses in 10.0.0.0/28] ************************
# ok: [localhost] => {
#     "ansible_facts": {
#         "data": {
#             "number_of_ips": 16,
#             "usable_ips": [
#                 "10.0.0.0",
#                 "10.0.0.1",
#                 "10.0.0.2",
#                 "10.0.0.3",
#                 "10.0.0.4",
#                 "10.0.0.5",
#                 "10.0.0.6",
#                 "10.0.0.7",
#                 "10.0.0.8",
#                 "10.0.0.9",
#                 "10.0.0.10",
#                 "10.0.0.11",
#                 "10.0.0.12",
#                 "10.0.0.13",
#                 "10.0.0.14",
#                 "10.0.0.15"
#             ]
#         }
#     },
#     "changed": false
# }

- name: Expand and produce list of usable IP addresses in 2001:db8:abcd:0012::0/126
  ansible.builtin.set_fact:
    data1: "{{ '2001:db8:abcd:0012::0/126' | ansible.utils.usable_range }}"

# TASK [Expand and produce list of usable IP addresses in 2001:db8:abcd:0012::0/126] ***
# ok: [localhost] => {
#     "ansible_facts": {
#         "data1": {
#             "number_of_ips": 4,
#             "usable_ips": [
#                 "2001:db8:abcd:12::",
#                 "2001:db8:abcd:12::1",
#                 "2001:db8:abcd:12::2",
#                 "2001:db8:abcd:12::3"
#             ]
#         }
#     },
#     "changed": false
# }

- name: Expand and produce list of usable IP addresses in 10.1.1.1
  ansible.builtin.set_fact:
    data: "{{ '10.1.1.1' | ansible.utils.usable_range }}"

# TASK [Expand and produce list of usable IP addresses in 10.1.1.1] ***************************
# ok: [localhost] => {
#     "ansible_facts": {
#         "data": {
#             "number_of_ips": 1,
#             "usable_ips": [
#                 "10.1.1.1"
#             ]
#         }
#     },
#     "changed": false
# }

#### Simple Use-case (looping through the list result)

- name: Expand and produce list of usable IP addresses in 127.0.0.0/28
  ansible.builtin.set_fact:
    data1: "{{ '127.0.0.0/28' | ansible.utils.usable_range }}"

- name: Ping all but first IP addresses from the generated list
  shell: "ping -c 1 {{ item }}"
  loop: "{{ data1.usable_ips[1:] }}"

# TASK [Expand and produce list of usable IP addresses in 127.0.0.0/28] ******************************
# ok: [localhost]

# TASK [Ping all but first IP addresses from the generated list] *************************************
# changed: [localhost] => (item=127.0.0.1)
# changed: [localhost] => (item=127.0.0.2)
# changed: [localhost] => (item=127.0.0.3)
# changed: [localhost] => (item=127.0.0.4)
# changed: [localhost] => (item=127.0.0.5)
# changed: [localhost] => (item=127.0.0.6)
# changed: [localhost] => (item=127.0.0.7)
# changed: [localhost] => (item=127.0.0.8)
# changed: [localhost] => (item=127.0.0.9)
# changed: [localhost] => (item=127.0.0.10)
# changed: [localhost] => (item=127.0.0.11)
# changed: [localhost] => (item=127.0.0.12)
# changed: [localhost] => (item=127.0.0.13)
# changed: [localhost] => (item=127.0.0.14)
# changed: [localhost] => (item=127.0.0.15)

Return Values

Key	Data Type	Description	Returned
data		Total number of usable IP addresses under the key C(number_of_ips) List of usable IP addresses under the key C(usable_ips)

Authors

• Priyam Sahoo (@priyamsahoo)