Docs: Add code-block:: to examples in ipaddr filters doc(#75951)

* Add code-block elements to playbooks_filters_ipaddr
* Add punctuation to lead-in sentences for code blocks
pull/75950/head
Miroslav Brabenec 3 years ago committed by GitHub
parent 2a3aa66fbd
commit fa4a92f221
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

@ -21,7 +21,9 @@ available to manipulate IP subnets and MAC addresses.
To use this filter in Ansible, you need to install the `netaddr`_ Python library on
a computer on which you use Ansible (it is not required on remote hosts).
It can usually be installed with either your system package manager or using
``pip``::
``pip``:
.. code-block:: bash
pip install netaddr
@ -44,11 +46,15 @@ filters. To use the filter, pass a string to it:
{{ '192.0.2.0' | ansible.netcommon.ipaddr }}
You can also pass the values as variables::
You can also pass the values as variables:
.. code-block:: yaml+jinja
{{ myvar | ansible.netcommon.ipaddr }}
Here are some example test results of various input strings::
Here are some example test results of various input strings:
.. code-block:: none
# These values are valid IP addresses or network ranges
'192.168.0.1' -> 192.168.0.1
@ -69,15 +75,21 @@ Here are some example test results of various input strings::
Sometimes you need either IPv4 or IPv6 addresses. To filter only for a particular
type, ``ipaddr()`` filter has two "aliases", ``ipv4()`` and ``ipv6()``.
Example use of an IPv4 filter::
Example use of an IPv4 filter:
.. code-block:: yaml+jinja
{{ myvar | ansible.netcommon.ipv4 }}
A similar example of an IPv6 filter::
A similar example of an IPv6 filter:
.. code-block:: yaml+jinja
{{ myvar | ansible.netcommon.ipv6 }}
Here's some example test results to look for IPv4 addresses::
Here's some example test results to look for IPv4 addresses:
.. code-block:: none
'192.168.0.1' -> 192.168.0.1
'192.168.32.0/24' -> 192.168.32.0/24
@ -85,7 +97,9 @@ Here's some example test results to look for IPv4 addresses::
45443646733 -> False
'523454/24' -> 0.7.252.190/24
And the same data filtered for IPv6 addresses::
And the same data filtered for IPv6 addresses:
.. code-block:: none
'192.168.0.1' -> False
'192.168.32.0/24' -> False
@ -98,10 +112,12 @@ Filtering lists
^^^^^^^^^^^^^^^
You can filter entire lists - ``ipaddr()`` will return a list with values
valid for a particular query::
valid for a particular query.
.. code-block:: yaml+jinja
# Example list of values
test_list = ['192.24.2.1', 'host.fqdn', '::1', '192.168.32.0/24', 'fe80::100/10', True, '', '42540766412265424405338506004571095040/64']
test_list: ['192.24.2.1', 'host.fqdn', '::1', '192.168.32.0/24', 'fe80::100/10', True, '', '42540766412265424405338506004571095040/64']
# {{ test_list | ansible.netcommon.ipaddr }}
['192.24.2.1', '::1', '192.168.32.0/24', 'fe80::100/10', '2001:db8:32c:faad::/64']
@ -118,7 +134,9 @@ Wrapping IPv6 addresses in [ ] brackets
Some configuration files require IPv6 addresses to be "wrapped" in square
brackets (``[ ]``). To accomplish that, you can use the ``ipwrap()`` filter. It
will wrap all IPv6 addresses and leave any other strings intact::
will wrap all IPv6 addresses and leave any other strings intact.
.. code-block:: yaml+jinja
# {{ test_list | ansible.netcommon.ipwrap }}
['192.24.2.1', 'host.fqdn', '[::1]', '192.168.32.0/24', '[fe80::100]/10', True, '', '[2001:db8:32c:faad::]/64']
@ -126,7 +144,9 @@ will wrap all IPv6 addresses and leave any other strings intact::
As you can see, ``ipwrap()`` did not filter out non-IP address values, which is
usually what you want when for example you are mixing IP addresses with
hostnames. If you still want to filter out all non-IP address values, you can
chain both filters together::
chain both filters together.
.. code-block:: yaml+jinja
# {{ test_list | ansible.netcommon.ipaddr | ansible.netcommon.ipwrap }}
['192.24.2.1', '[::1]', '192.168.32.0/24', '[fe80::100]/10', '[2001:db8:32c:faad::]/64']
@ -151,13 +171,17 @@ If a query type is not recognized, Ansible will raise an error.
Getting information about hosts and networks
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Here's our test list again::
Here's our test list again:
.. code-block:: yaml+jinja
# Example list of values
test_list = ['192.24.2.1', 'host.fqdn', '::1', '192.168.32.0/24', 'fe80::100/10', True, '', '42540766412265424405338506004571095040/64']
test_list: ['192.24.2.1', 'host.fqdn', '::1', '192.168.32.0/24', 'fe80::100/10', True, '', '42540766412265424405338506004571095040/64']
Let's take the list above and get only those elements that are host IP addresses
and not network ranges::
and not network ranges:
.. code-block:: yaml+jinja
# {{ test_list | ansible.netcommon.ipaddr('address') }}
['192.24.2.1', '::1', 'fe80::100']
@ -165,12 +189,16 @@ and not network ranges::
As you can see, even though some values had a host address with a CIDR prefix,
they were dropped by the filter. If you want host IP addresses with their correct
CIDR prefixes (as is common with IPv6 addressing), you can use the
``ipaddr('host')`` filter::
``ipaddr('host')`` filter.
.. code-block:: yaml+jinja
# {{ test_list | ansible.netcommon.ipaddr('host') }}
['192.24.2.1/32', '::1/128', 'fe80::100/10']
Filtering by IP address type also works::
Filtering by IP address type also works.
.. code-block:: yaml+jinja
# {{ test_list | ansible.netcommon.ipv4('address') }}
['192.24.2.1']
@ -179,7 +207,9 @@ Filtering by IP address type also works::
['::1', 'fe80::100']
You can check if IP addresses or network ranges are accessible on a public
Internet, or if they are in private networks::
Internet, or if they are in private networks:
.. code-block:: yaml+jinja
# {{ test_list | ansible.netcommon.ipaddr('public') }}
['192.24.2.1', '2001:db8:32c:faad::/64']
@ -187,25 +217,33 @@ Internet, or if they are in private networks::
# {{ test_list | ansible.netcommon.ipaddr('private') }}
['192.168.32.0/24', 'fe80::100/10']
You can check which values are specifically network ranges::
You can check which values are specifically network ranges:
.. code-block:: yaml+jinja
# {{ test_list | ansible.netcommon.ipaddr('net') }}
['192.168.32.0/24', '2001:db8:32c:faad::/64']
You can also check how many IP addresses can be in a certain range::
You can also check how many IP addresses can be in a certain range.
.. code-block:: yaml+jinja
# {{ test_list | ansible.netcommon.ipaddr('net') | ansible.netcommon.ipaddr('size') }}
[256, 18446744073709551616L]
By specifying a network range as a query, you can check if a given value is in
that range::
that range.
.. code-block:: yaml+jinja
# {{ test_list | ansible.netcommon.ipaddr('192.0.0.0/8') }}
['192.24.2.1', '192.168.32.0/24']
If you specify a positive or negative integer as a query, ``ipaddr()`` will
treat this as an index and will return the specific IP address from a network
range, in the 'host/prefix' format::
range, in the 'host/prefix' format.
.. code-block:: yaml+jinja
# First IP address (network address)
# {{ test_list | ansible.netcommon.ipaddr('net') | ansible.netcommon.ipaddr('0') }}
@ -220,7 +258,9 @@ range, in the 'host/prefix' format::
['192.168.32.255/24', '2001:db8:32c:faad:ffff:ffff:ffff:ffff/64']
You can also select IP addresses from a range by their index, from the start or
end of the range::
end of the range.
.. code-block:: yaml+jinja
# Returns from the start of the range
# {{ test_list | ansible.netcommon.ipaddr('net') | ansible.netcommon.ipaddr('200') }}
@ -241,12 +281,16 @@ You frequently use a combination of IP addresses and subnet prefixes
("CIDR"), this is even more common with IPv6. The ``ansible.netcommon.ipaddr()`` filter can extract
useful data from these prefixes.
Here's an example set of two host prefixes (with some "control" values)::
Here's an example set of two host prefixes (with some "control" values):
host_prefix = ['2001:db8:deaf:be11::ef3/64', '192.0.2.48/24', '127.0.0.1', '192.168.0.0/16']
.. code-block:: yaml+jinja
host_prefix: ['2001:db8:deaf:be11::ef3/64', '192.0.2.48/24', '127.0.0.1', '192.168.0.0/16']
First, let's make sure that we only work with correct host/prefix values, not
just subnets or single IP addresses::
just subnets or single IP addresses.
.. code-block:: yaml+jinja
# {{ host_prefix | ansible.netcommon.ipaddr('host/prefix') }}
['2001:db8:deaf:be11::ef3/64', '192.0.2.48/24']
@ -305,7 +349,9 @@ If needed, you can extract subnet and prefix information from the 'host/prefix'
Converting subnet masks to CIDR notation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Given a subnet in the form of network address and subnet mask, the ``ipaddr()`` filter can convert it into CIDR notation. This can be useful for converting Ansible facts gathered about network configuration from subnet masks into CIDR format::
Given a subnet in the form of network address and subnet mask, the ``ipaddr()`` filter can convert it into CIDR notation. This can be useful for converting Ansible facts gathered about network configuration from subnet masks into CIDR format.
.. code-block:: yaml+jinja
ansible_default_ipv4: {
address: "192.168.0.11",
@ -320,12 +366,16 @@ Given a subnet in the form of network address and subnet mask, the ``ipaddr()``
type: "ether"
}
First concatenate the network and netmask::
First concatenate the network and netmask:
.. code-block:: yaml+jinja
net_mask = "{{ ansible_default_ipv4.network }}/{{ ansible_default_ipv4.netmask }}"
net_mask: "{{ ansible_default_ipv4.network }}/{{ ansible_default_ipv4.netmask }}"
'192.168.0.0/255.255.255.0'
This result can be converted to canonical form with ``ipaddr()`` to produce a subnet in CIDR format::
This result can be converted to canonical form with ``ipaddr()`` to produce a subnet in CIDR format.
.. code-block:: yaml+jinja
# {{ net_mask | ansible.netcommon.ipaddr('prefix') }}
'24'
@ -340,12 +390,16 @@ Getting information about the network in CIDR notation
Given an IP address, the ``ipaddr()`` filter can produce the network address in CIDR notation.
This can be useful when you want to obtain the network address from the IP address in CIDR format.
Here's an example of IP address::
Here's an example of IP address:
.. code-block:: yaml+jinja
ip_address = "{{ ansible_default_ipv4.address }}/{{ ansible_default_ipv4.netmask }}"
ip_address: "{{ ansible_default_ipv4.address }}/{{ ansible_default_ipv4.netmask }}"
'192.168.0.11/255.255.255.0'
This can be used to obtain the network address in CIDR notation format::
This can be used to obtain the network address in CIDR notation format.
.. code-block:: yaml+jinja
# {{ ip_address | ansible.netcommon.ipaddr('network/prefix') }}
'192.168.0.0/24'
@ -354,40 +408,54 @@ This can be used to obtain the network address in CIDR notation format::
IP address conversion
^^^^^^^^^^^^^^^^^^^^^
Here's our test list again::
Here's our test list again:
.. code-block:: yaml+jinja
# Example list of values
test_list = ['192.24.2.1', 'host.fqdn', '::1', '192.168.32.0/24', 'fe80::100/10', True, '', '42540766412265424405338506004571095040/64']
test_list: ['192.24.2.1', 'host.fqdn', '::1', '192.168.32.0/24', 'fe80::100/10', True, '', '42540766412265424405338506004571095040/64']
You can convert IPv4 addresses into IPv6 addresses::
You can convert IPv4 addresses into IPv6 addresses.
.. code-block:: yaml+jinja
# {{ test_list | ansible.netcommon.ipv4('ipv6') }}
['::ffff:192.24.2.1/128', '::ffff:192.168.32.0/120']
Converting from IPv6 to IPv4 works very rarely::
Converting from IPv6 to IPv4 works very rarely
.. code-block:: yaml+jinja
# {{ test_list | ansible.netcommon.ipv6('ipv4') }}
['0.0.0.1/32']
But we can make a double conversion if needed::
But we can make a double conversion if needed:
.. code-block:: yaml+jinja
# {{ test_list | ansible.netcommon.ipaddr('ipv6') | ansible.netcommon.ipaddr('ipv4') }}
['192.24.2.1/32', '0.0.0.1/32', '192.168.32.0/24']
You can convert IP addresses to integers, the same way that you can convert
integers into IP addresses::
integers into IP addresses.
.. code-block:: yaml+jinja
# {{ test_list | ansible.netcommon.ipaddr('address') | ansible.netcommon.ipaddr('int') }}
[3222798849, 1, '3232243712/24', '338288524927261089654018896841347694848/10', '42540766412265424405338506004571095040/64']
You can convert IPv4 address to `Hexadecimal notation <https://en.wikipedia.org/wiki/Hexadecimal>`_ with optional delimiter::
You can convert IPv4 address to `Hexadecimal notation <https://en.wikipedia.org/wiki/Hexadecimal>`_ with optional delimiter:
.. code-block:: yaml+jinja
# {{ '192.168.1.5' | ansible.netcommon.ip4_hex }}
c0a80105
# {{ '192.168.1.5' | ansible.netcommon.ip4_hex(':') }}
c0:a8:01:05
You can convert IP addresses to PTR records::
You can convert IP addresses to PTR records:
.. code-block:: yaml+jinja
# {% for address in test_list | ansible.netcommon.ipaddr %}
# {{ address | ansible.netcommon.ipaddr('revdns') }}
@ -409,7 +477,9 @@ access to a ``2002:xxxx:xxxx::/48`` subnet which could be split into 65535
``/64`` subnets if needed.
To convert your IPv4 address, just send it through the ``'6to4'`` filter. It will
be automatically converted to a router address (with a ``::1/48`` host address)::
be automatically converted to a router address (with a ``::1/48`` host address).
.. code-block:: yaml+jinja
# {{ '193.0.2.0' | ansible.netcommon.ipaddr('6to4') }}
2002:c100:0200::1/48
@ -422,50 +492,68 @@ Finding IP addresses within a range
To find usable IP addresses within an IP range, try these ``ipaddr`` filters:
To find the next usable IP address in a range, use ``next_usable`` ::
To find the next usable IP address in a range, use ``next_usable``:
.. code-block:: yaml+jinja
# {{ '192.168.122.1/24' | ansible.netcommon.ipaddr('next_usable') }}
192.168.122.2
To find the last usable IP address from a range, use ``last_usable``::
To find the last usable IP address from a range, use ``last_usable``.
.. code-block:: yaml+jinja
# {{ '192.168.122.1/24' | ansible.netcommon.ipaddr('last_usable') }}
192.168.122.254
To find the available range of IP addresses from the given network address, use ``range_usable``::
To find the available range of IP addresses from the given network address, use ``range_usable``.
.. code-block:: yaml+jinja
# {{ '192.168.122.1/24' | ansible.netcommon.ipaddr('range_usable') }}
192.168.122.1-192.168.122.254
To find the peer IP address for a point to point link, use ``peer``::
To find the peer IP address for a point to point link, use ``peer``.
.. code-block:: yaml+jinja
# {{ '192.168.122.1/31' | ansible.netcommon.ipaddr('peer') }}
192.168.122.0
# {{ '192.168.122.1/30' | ansible.netcommon.ipaddr('peer') }}
192.168.122.2
To return the nth ip from a network, use the filter ``nthhost``::
To return the nth ip from a network, use the filter ``nthhost``.
.. code-block:: yaml+jinja
# {{ '10.0.0.0/8' | ansible.netcommon.nthhost(305) }}
10.0.1.49
``nthhost`` also supports a negative value::
``nthhost`` also supports a negative value.
.. code-block:: yaml+jinja
# {{ '10.0.0.0/8' | ansible.netcommon.nthhost(-1) }}
10.255.255.255
To find the next nth usable IP address in relation to another within a range, use ``next_nth_usable``
In the example, ``next_nth_usable`` returns the second usable IP address for the given IP range::
In the example, ``next_nth_usable`` returns the second usable IP address for the given IP range:
.. code-block:: yaml+jinja
# {{ '192.168.122.1/24' | ansible.netcommon.next_nth_usable(2) }}
192.168.122.3
If there is no usable address, it returns an empty string::
If there is no usable address, it returns an empty string.
.. code-block:: yaml+jinja
# {{ '192.168.122.254/24' | ansible.netcommon.next_nth_usable(2) }}
""
Just like ``next_nth_ansible``, you have ``previous_nth_usable`` to find the previous usable address::
Just like ``next_nth_ansible``, you have ``previous_nth_usable`` to find the previous usable address:
.. code-block:: yaml+jinja
# {{ '192.168.122.10/24' | ansible.netcommon.previous_nth_usable(2) }}
192.168.122.8
@ -476,7 +564,9 @@ Testing if a address belong to a network range
The ``network_in_usable`` filter returns whether an address passed as an argument is usable in a network.
Usable addresses are addresses that can be assigned to a host. The network ID and the broadcast address
are not usable addresses.::
are not usable addresses.
.. code-block:: yaml+jinja
# {{ '192.168.0.0/24' | ansible.netcommon.network_in_usable( '192.168.0.1' ) }}
True
@ -487,7 +577,9 @@ are not usable addresses.::
# {{ '192.168.0.0/16' | ansible.netcommon.network_in_usable( '192.168.0.255' ) }}
True
The ``network_in_network`` filter returns whether an address or a network passed as argument is in a network.::
The ``network_in_network`` filter returns whether an address or a network passed as argument is in a network.
.. code-block:: yaml+jinja
# {{ '192.168.0.0/24' | ansible.netcommon.network_in_network( '192.168.0.1' ) }}
True
@ -502,7 +594,9 @@ The ``network_in_network`` filter returns whether an address or a network passed
# {{ '192.168.0.0/16' | ansible.netcommon.network_in_network( '192.168.0.0/24' ) }}
True
To check whether multiple addresses belong to a network, use the ``reduce_on_network`` filter::
To check whether multiple addresses belong to a network, use the ``reduce_on_network`` filter.
.. code-block:: yaml+jinja
# {{ ['192.168.0.34', '10.3.0.3', '192.168.2.34'] | ansible.netcommon.reduce_on_network( '192.168.0.0/24' ) }}
['192.168.0.34']
@ -515,7 +609,9 @@ IP Math
The ``ipmath()`` filter can be used to do simple IP math/arithmetic.
Here are a few simple examples::
Here are a few simple examples:
.. code-block:: yaml+jinja
# Get the next five addresses based on an IP address
# {{ '192.168.1.5' | ansible.netcommon.ipmath(5) }}
@ -553,14 +649,18 @@ Subnet manipulation
The ``ipsubnet()`` filter can be used to manipulate network subnets in several ways.
Here is an example IP address and subnet::
Here is an example IP address and subnet:
address = '192.168.144.5'
subnet = '192.168.0.0/16'
.. code-block:: yaml+jinja
address: '192.168.144.5'
subnet: '192.168.0.0/16'
To check if a given string is a subnet, pass it through the filter without any
arguments. If the given string is an IP address, it will be converted into
a subnet::
a subnet.
.. code-block:: yaml+jinja
# {{ address | ansible.netcommon.ipsubnet }}
192.168.144.5/32
@ -570,13 +670,17 @@ a subnet::
If you specify a subnet size as the first parameter of the ``ipsubnet()`` filter, and
the subnet size is **smaller than the current one**, you will get the number of subnets
a given subnet can be split into::
a given subnet can be split into.
.. code-block:: yaml+jinja
# {{ subnet | ansible.netcommon.ipsubnet(20) }}
16
The second argument of the ``ipsubnet()`` filter is an index number; by specifying it
you can get a new subnet with the specified size::
you can get a new subnet with the specified size.
.. code-block:: yaml+jinja
# First subnet
# {{ subnet | ansible.netcommon.ipsubnet(20, 0) }}
@ -596,13 +700,17 @@ you can get a new subnet with the specified size::
If you specify an IP address instead of a subnet, and give a subnet size as
the first argument, the ``ipsubnet()`` filter will instead return the biggest subnet that
contains that given IP address::
contains that given IP address.
.. code-block:: yaml+jinja
# {{ address | ansible.netcommon.ipsubnet(20) }}
192.168.144.0/20
By specifying an index number as a second argument, you can select smaller and
smaller subnets::
smaller subnets.
.. code-block:: yaml+jinja
# First subnet
# {{ address | ansible.netcommon.ipsubnet(18, 0) }}
@ -621,7 +729,9 @@ smaller subnets::
192.168.144.0/27
By specifying another subnet as a second argument, if the second subnet includes
the first, you can determine the rank of the first subnet in the second ::
the first, you can determine the rank of the first subnet in the second.
.. code-block:: yaml+jinja
# The rank of the IP in the subnet (the IP is the 36870nth /32 of the subnet)
# {{ address | ansible.netcommon.ipsubnet(subnet) }}
@ -643,7 +753,9 @@ If the second subnet doesn't include the first subnet, the ``ipsubnet()`` filter
You can use the ``ipsubnet()`` filter with the ``ipaddr()`` filter to, for example, split
a given ``/48`` prefix into smaller ``/64`` subnets::
a given ``/48`` prefix into smaller ``/64`` subnets:
.. code-block:: yaml+jinja
# {{ '193.0.2.0' | ansible.netcommon.ipaddr('6to4') | ipsubnet(64, 58820) | ansible.netcommon.ipaddr('1') }}
2002:c100:200:e5c4::1/64
@ -660,7 +772,9 @@ Subnet Merging
The ``cidr_merge()`` filter can be used to merge subnets or individual addresses
into their minimal representation, collapsing overlapping subnets and merging
adjacent ones wherever possible::
adjacent ones wherever possible.
.. code-block:: yaml+jinja
{{ ['192.168.0.0/17', '192.168.128.0/17', '192.168.128.1' ] | cidr_merge }}
# => ['192.168.0.0/16']
@ -669,7 +783,9 @@ adjacent ones wherever possible::
# => ['192.168.0.0/23', '192.168.3.0/24']
Changing the action from 'merge' to 'span' will instead return the smallest
subnet which contains all of the inputs::
subnet which contains all of the inputs.
.. code-block:: yaml+jinja
{{ ['192.168.0.0/24', '192.168.3.0/24'] | ansible.netcommon.cidr_merge('span') }}
# => '192.168.0.0/22'
@ -682,10 +798,12 @@ MAC address filter
^^^^^^^^^^^^^^^^^^
You can use the ``hwaddr()`` filter to check if a given string is a MAC address or
convert it between various formats. Examples::
convert it between various formats. Examples:
.. code-block:: yaml+jinja
# Example MAC address
macaddress = '1a:2b:3c:4d:5e:6f'
macaddress: '1a:2b:3c:4d:5e:6f'
# Check if given string is a MAC address
# {{ macaddress | ansible.netcommon.hwaddr }}
@ -699,7 +817,9 @@ convert it between various formats. Examples::
# {{ macaddress | ansible.netcommon.hwaddr('cisco') }}
1a2b.3c4d.5e6f
The supported formats result in the following conversions for the ``1a:2b:3c:4d:5e:6f`` MAC address::
The supported formats result in the following conversions for the ``1a:2b:3c:4d:5e:6f`` MAC address:
.. code-block:: yaml+jinja
bare: 1A2B3C4D5E6F
bool: True
@ -713,7 +833,9 @@ The supported formats result in the following conversions for the ``1a:2b:3c:4d:
Generate an IPv6 address in Stateless Configuration (SLAAC)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
the filter ``slaac()`` generates an IPv6 address for a given network and a MAC Address in Stateless Configuration::
the filter ``slaac()`` generates an IPv6 address for a given network and a MAC Address in Stateless Configuration.
.. code-block:: yaml+jinja
# {{ 'fdcf:1894:23b5:d38c:0000:0000:0000:0000' | slaac('c2:31:b3:83:bf:2b') }}
fdcf:1894:23b5:d38c:c031:b3ff:fe83:bf2b
@ -740,4 +862,3 @@ the filter ``slaac()`` generates an IPv6 address for a given network and a MAC A
Have a question? Stop by the google group!
:ref:`communication_irc`
How to join Ansible chat channels

Loading…
Cancel
Save