Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add documentation for ipaddr filters #70343

Merged
merged 17 commits into from Jul 2, 2020
Merged

Add documentation for ipaddr filters #70343

Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
fc5203e
Add documentation for filters network_in_network and network_in_usable
bmillemathias Jun 27, 2020
5cd6f8d
Add documentation about ipaddr filter previous_nth_usable
bmillemathias Jun 27, 2020
4256977
Move all ipaddr filters together
bmillemathias Jun 27, 2020
d863045
Document ipaddr filter nthhost
bmillemathias Jun 27, 2020
2096a3c
Add example for filter slaac
bmillemathias Jun 28, 2020
7bd0b21
Fix wording and typo spot by Akasurde
bmillemathias Jun 28, 2020
c467441
Add example for filter reduce_on_network
bmillemathias Jun 28, 2020
87852a0
Fix another typo
bmillemathias Jun 28, 2020
c2075ca
Update docs/docsite/rst/user_guide/playbooks_filters_ipaddr.rst
bmillemathias Jul 1, 2020
1f27c44
Update docs/docsite/rst/user_guide/playbooks_filters_ipaddr.rst
bmillemathias Jul 1, 2020
0daa556
Update docs/docsite/rst/user_guide/playbooks_filters_ipaddr.rst
bmillemathias Jul 1, 2020
f80951d
Update docs/docsite/rst/user_guide/playbooks_filters_ipaddr.rst
bmillemathias Jul 1, 2020
994c4f1
Update docs/docsite/rst/user_guide/playbooks_filters_ipaddr.rst
bmillemathias Jul 1, 2020
6020f6b
Update docs/docsite/rst/user_guide/playbooks_filters_ipaddr.rst
bmillemathias Jul 1, 2020
aad7ee1
Apply suggestions from code review
bmillemathias Jul 1, 2020
6425464
Add double space before sections title
bmillemathias Jul 1, 2020
67fd3c1
Title underline was too short and made the build fail
bmillemathias Jul 1, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
98 changes: 90 additions & 8 deletions docs/docsite/rst/user_guide/playbooks_filters_ipaddr.rst
View file
Open in desktop
Expand Up @@ -32,6 +32,7 @@ It can usually be installed with either your system package manager or using
:depth: 2
:backlinks: top


Basic tests
^^^^^^^^^^^

Expand Down Expand Up @@ -293,12 +294,15 @@ on an interface:

If needed, you can extract subnet and prefix information from the 'host/prefix' value::

.. code-block:: jinja

# {{ host_prefix | ansible.netcommon.ipaddr('host/prefix') | ansible.netcommon.ipaddr('subnet') }}
['2001:db8:deaf:be11::/64', '192.0.2.0/24']

# {{ host_prefix | ansible.netcommon.ipaddr('host/prefix') | ansible.netcommon.ipaddr('prefix') }}
[64, 24]


Converting subnet masks to CIDR notation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Expand Down Expand Up @@ -330,6 +334,7 @@ This result can be converted to canonical form with ``ipaddr()`` to produce a su
# {{ net_mask | ansible.netcommon.ipaddr('net') }}
'192.168.0.0/24'


Getting information about the network in CIDR notation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Expand All @@ -346,6 +351,7 @@ This can be used to obtain the network address in CIDR notation format::
# {{ ip_address | ansible.netcommon.ipaddr('network/prefix') }}
'192.168.0.0/24'


IP address conversion
^^^^^^^^^^^^^^^^^^^^^

Expand Down Expand Up @@ -411,6 +417,7 @@ be automatically converted to a router address (with a ``::1/48`` host address):

.. _6to4: https://en.wikipedia.org/wiki/6to4


Finding IP addresses within a range
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Expand All @@ -431,20 +438,76 @@ To find the available range of IP addresses from the given network address, use
# {{ '192.168.122.1/24' | ansible.netcommon.ipaddr('range_usable') }}
192.168.122.1-192.168.122.254

To find the next nth usable IP address within a range, use ``next_nth_usable``::

# {{ '192.168.122.1/24' | ansible.netcommon.next_nth_usable(2) }}
192.168.122.3

In this example, ``next_nth_usable`` returns the second usable IP address for the given IP range.

To find the peer IP address for a point to point link, use ``peer``::

# {{ '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``::
bmillemathias marked this conversation as resolved.
Show resolved Hide resolved

# {{ '10.0.0.0/8' | ansible.netcommon.nthhost(305) }}
10.0.1.49

``nthhost`` also supports a negative value::

# {{ '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::

# {{ '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::

# {{ '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::

# {{ '192.168.122.10/24' | ansible.netcommon.previous_nth_usable(2) }}
192.168.122.8


Testing if a address belong to a network range
bmillemathias marked this conversation as resolved.
Show resolved Hide resolved
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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.::

# {{ '192.168.0.0/24' | ansible.netcommon.network_in_usable( '192.168.0.1' ) }}
True

# {{ '192.168.0.0/24' | ansible.netcommon.network_in_usable( '192.168.0.255' ) }}
False

# {{ '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.::

# {{ '192.168.0.0/24' | ansible.netcommon.network_in_network( '192.168.0.1' ) }}
True

# {{ '192.168.0.0/24' | ansible.netcommon.network_in_network( '192.168.0.0/24' ) }}
True

# {{ '192.168.0.0/24' | ansible.netcommon.network_in_network( '192.168.0.255' ) }}
True

# Check in a network is part of another network
# {{ '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::

# {{ '192.168.0.0/24' | ansible.netcommon.reduce_on_network( ['192.168.0.34', '10.3.0.3', '192.168.2.34'] ) }}
['192.168.0.34']


IP Math
^^^^^^^
Expand All @@ -455,24 +518,32 @@ The ``ipmath()`` filter can be used to do simple IP math/arithmetic.

Here are a few simple examples::

# Get the next five addresses based on an IP address
# {{ '192.168.1.5' | ansible.netcommon.ipmath(5) }}
192.168.1.10

# Get the ten previous addresses based on an IP address
# {{ '192.168.0.5' | ansible.netcommon.ipmath(-10) }}
192.167.255.251

# Get the next five addresses using CIDR notation
# {{ '192.168.1.1/24' | ansible.netcommon.ipmath(5) }}
192.168.1.6

# Get the previous five addresses using CIDR notation
# {{ '192.168.1.6/24' | ansible.netcommon.ipmath(-5) }}
192.168.1.1

# Get the previous ten address using cidr notation
bmillemathias marked this conversation as resolved.
Show resolved Hide resolved
# It returns a address of the previous network range
bmillemathias marked this conversation as resolved.
Show resolved Hide resolved
# {{ '192.168.2.6/24' | ansible.netcommon.ipmath(-10) }}
192.168.1.252

# Get the next ten addresses in IPv6
# {{ '2001::1' | ansible.netcommon.ipmath(10) }}
2001::b

# Get the previous ten address in IPv6
bmillemathias marked this conversation as resolved.
Show resolved Hide resolved
# {{ '2001::5' | ansible.netcommon.ipmath(-10) }}
2000:ffff:ffff:ffff:ffff:ffff:ffff:fffb

Expand Down Expand Up @@ -582,6 +653,7 @@ Because of the size of IPv6 subnets, iteration over all of them to find the
correct one may take some time on slower computers, depending on the size
difference between the subnets.


Subnet Merging
^^^^^^^^^^^^^^

Expand All @@ -606,6 +678,7 @@ subnet which contains all of the inputs::
{{ ['192.168.1.42', '192.168.42.1'] | ansible.netcommon.cidr_merge('span') }}
# => '192.168.0.0/18'


MAC address filter
^^^^^^^^^^^^^^^^^^

Expand Down Expand Up @@ -637,11 +710,20 @@ The supported formats result in the following conversions for the ``1a:2b:3c:4d:
linux or unix: 1a:2b:3c:4d:5e:6f:
pgsql, postgresql, or psql: 1a2b3c:4d5e6f


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::

# {{ fdcf:1894:23b5:d38c:0000:0000:0000:0000 | slaac('c2:31:b3:83:bf:2b') }}
fdcf:1894:23b5:d38c:c031:b3ff:fe83:bf2b

.. seealso::


`ansible.netcommon <https://galaxy.ansible.com/ansible/netcommon>`_
Ansible network collection for common code
Ansible network collection for common code
:ref:`about_playbooks`
An introduction to playbooks
:ref:`playbooks_filters`
Expand Down