cmueller/ansible
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

fixed grammar and spelling issues (#44931)

Browse source 
* fixed grammar and spelling issues

* fixed autocorrect mistake and sanity test errors
This commit is contained in:
Sandra McCann 2018-08-31 09:44:31 -04:00 committed by Alicia Cozine
parent 3f657ca28f
commit cccf5e6e77
1 changed files with 64 additions and 60 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

124
docs/docsite/rst/user_guide/playbooks_filters_ipaddr.rst
View file

@ -5,16 +5,16 @@ ipaddr filter
.. versionadded:: 1.9 .. versionadded:: 1.9
``ipaddr()`` is a Jinja2 filter designed to provide an interface to `netaddr`_ ``ipaddr()`` is a Jinja2 filter designed to provide an interface to the `netaddr`_
Python package from within Ansible. It can operate on strings or lists of Python package from within Ansible. It can operate on strings or lists of
items, test various data to check if they are valid IP addresses and manipulate items, test various data to check if they are valid IP addresses, and manipulate
the input data to extract requested information. ``ipaddr()`` works both with the input data to extract requested information. ``ipaddr()`` works with both
IPv4 and IPv6 addresses in various forms, there are also additional functions IPv4 and IPv6 addresses in various forms. There are also additional functions
available to manipulate IP subnets and MAC addresses. available to manipulate IP subnets and MAC addresses.
To use this filter in Ansible, you need to install `netaddr`_ Python library on 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). a computer on which you use Ansible (it is not required on remote hosts).
It can usually be installed either via your system package manager, or using It can usually be installed with either your system package manager or using
``pip``:: ``pip``::
pip install netaddr pip install netaddr
@ -30,8 +30,8 @@ Basic tests
^^^^^^^^^^^ ^^^^^^^^^^^
``ipaddr()`` is designed to return the input value if a query is True, and ``ipaddr()`` is designed to return the input value if a query is True, and
``False`` if query is False. This way it can be very easily used in chained ``False`` if a query is False. This way it can be easily used in chained
filters. To use the filter, pass a string to it filters. To use the filter, pass a string to it:
.. code-block:: none .. code-block:: none
@ -41,7 +41,7 @@ You can also pass the values as variables::
{{ myvar | ipaddr }} {{ myvar | ipaddr }}
Here are some example tests of various input strings:: Here are some example test results of various input strings::
# These values are valid IP addresses or network ranges # These values are valid IP addresses or network ranges
'192.168.0.1' -> 192.168.0.1 '192.168.0.1' -> 192.168.0.1
@ -50,7 +50,7 @@ Here are some example tests of various input strings::
45443646733 -> ::a:94a7:50d 45443646733 -> ::a:94a7:50d
'523454/24' -> 0.7.252.190/24 '523454/24' -> 0.7.252.190/24
# Values that are not valid IP addresses or network ranges: # Values that are not valid IP addresses or network ranges
'localhost' -> False 'localhost' -> False
True -> False True -> False
'space bar' -> False 'space bar' -> False
@ -59,18 +59,18 @@ Here are some example tests of various input strings::
':' -> False ':' -> False
'fe80:/10' -> False 'fe80:/10' -> False
Sometimes you need either IPv4 or IPv6 addresses. To filter only for particular Sometimes you need either IPv4 or IPv6 addresses. To filter only for a particular
type, ``ipaddr()`` filter has two "aliases", ``ipv4()`` and ``ipv6()``. type, ``ipaddr()`` filter has two "aliases", ``ipv4()`` and ``ipv6()``.
Example us of an IPv4 filter:: Example use of an IPv4 filter::
{{ myvar | ipv4 }} {{ myvar | ipv4 }}
And similar example of an IPv6 filter:: A similar example of an IPv6 filter::
{{ myvar | ipv6 }} {{ myvar | ipv6 }}
Here's an example test to look for IPv4 addresses:: Here's some example test results to look for IPv4 addresses::
'192.168.0.1' -> 192.168.0.1 '192.168.0.1' -> 192.168.0.1
'192.168.32.0/24' -> 192.168.32.0/24 '192.168.32.0/24' -> 192.168.32.0/24
@ -110,7 +110,7 @@ Wrapping IPv6 addresses in [ ] brackets
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Some configuration files require IPv6 addresses to be "wrapped" in square Some configuration files require IPv6 addresses to be "wrapped" in square
brackets (``[ ]``). To accomplish that, you can use ``ipwrap()`` filter. It 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::
# {{ test_list | ipwrap }} # {{ test_list | ipwrap }}
@ -128,7 +128,7 @@ chain both filters together::
Basic queries Basic queries
^^^^^^^^^^^^^ ^^^^^^^^^^^^^
You can provide single argument to each ``ipaddr()`` filter. Filter will then You can provide a single argument to each ``ipaddr()`` filter. The filter will then
treat it as a query and return values modified by that query. Lists will treat it as a query and return values modified by that query. Lists will
contain only values that you are querying for. contain only values that you are querying for.
@ -149,21 +149,21 @@ Here's our test list again::
# Example list of values # 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']
Lets take above list and get only those elements that are host IP addresses, Let's take the list above and get only those elements that are host IP addresses
and not network ranges:: and not network ranges::
# {{ test_list | ipaddr('address') }} # {{ test_list | ipaddr('address') }}
['192.24.2.1', '::1', 'fe80::100'] ['192.24.2.1', '::1', 'fe80::100']
As you can see, even though some values had a host address with a CIDR prefix, As you can see, even though some values had a host address with a CIDR prefix,
it was dropped by the filter. If you want host IP addresses with their correct 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 CIDR prefixes (as is common with IPv6 addressing), you can use the
``ipaddr('host')`` filter:: ``ipaddr('host')`` filter::
# {{ test_list | ipaddr('host') }} # {{ test_list | ipaddr('host') }}
['192.24.2.1/32', '::1/128', 'fe80::100/10'] ['192.24.2.1/32', '::1/128', 'fe80::100/10']
Filtering by IP address types also works:: Filtering by IP address type also works::
# {{ test_list | ipv4('address') }} # {{ test_list | ipv4('address') }}
['192.24.2.1'] ['192.24.2.1']
@ -190,34 +190,36 @@ You can also check how many IP addresses can be in a certain range::
# {{ test_list | ipaddr('net') | ipaddr('size') }} # {{ test_list | ipaddr('net') | ipaddr('size') }}
[256, 18446744073709551616L] [256, 18446744073709551616L]
By specifying a network range as a query, you can check if given value is in By specifying a network range as a query, you can check if a given value is in
that range:: that range::
# {{ test_list | ipaddr('192.0.0.0/8') }} # {{ test_list | ipaddr('192.0.0.0/8') }}
['192.24.2.1', '192.168.32.0/24'] ['192.24.2.1', '192.168.32.0/24']
If you specify a positive or negative integer as a query, ``ipaddr()`` will If you specify a positive or negative integer as a query, ``ipaddr()`` will
treat this as an index and will return specific IP address from a network 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::
# First IP address (network address) # First IP address (network address)
# {{ test_list | ipaddr('net') | ipaddr('0') }} # {{ test_list | ipaddr('net') | ipaddr('0') }}
['192.168.32.0/24', '2001:db8:32c:faad::/64'] ['192.168.32.0/24', '2001:db8:32c:faad::/64']
# Second IP address (usually gateway host) # Second IP address (usually the gateway host)
# {{ test_list | ipaddr('net') | ipaddr('1') }} # {{ test_list | ipaddr('net') | ipaddr('1') }}
['192.168.32.1/24', '2001:db8:32c:faad::1/64'] ['192.168.32.1/24', '2001:db8:32c:faad::1/64']
# Last IP address (broadcast in IPv4 networks) # Last IP address (the broadcast address in IPv4 networks)
# {{ test_list | ipaddr('net') | ipaddr('-1') }} # {{ test_list | ipaddr('net') | ipaddr('-1') }}
['192.168.32.255/24', '2001:db8:32c:faad:ffff:ffff:ffff:ffff/64'] ['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 You can also select IP addresses from a range by their index, from the start or
end of the range:: end of the range::
# Returns from the start of the range
# {{ test_list | ipaddr('net') | ipaddr('200') }} # {{ test_list | ipaddr('net') | ipaddr('200') }}
['192.168.32.200/24', '2001:db8:32c:faad::c8/64'] ['192.168.32.200/24', '2001:db8:32c:faad::c8/64']
# Returns from the end of the range
# {{ test_list | ipaddr('net') | ipaddr('-200') }} # {{ test_list | ipaddr('net') | ipaddr('-200') }}
['192.168.32.56/24', '2001:db8:32c:faad:ffff:ffff:ffff:ff38/64'] ['192.168.32.56/24', '2001:db8:32c:faad:ffff:ffff:ffff:ff38/64']
@ -228,8 +230,8 @@ end of the range::
Getting information from host/prefix values Getting information from host/prefix values
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Very frequently you use combination of IP addresses and subnet prefixes You frequently use a combination of IP addresses and subnet prefixes
("CIDR"), this is even more common with IPv6. ``ipaddr()`` filter can extract ("CIDR"), this is even more common with IPv6. The ``ipaddr()`` filter can extract
useful data from these prefixes. 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)::
@ -242,7 +244,7 @@ just subnets or single IP addresses::
# {{ host_prefix | ipaddr('host/prefix') }} # {{ host_prefix | ipaddr('host/prefix') }}
['2001:db8:deaf:be11::ef3/64', '192.0.2.48/24'] ['2001:db8:deaf:be11::ef3/64', '192.0.2.48/24']
In Debian-based systems, network configuration stored in ``/etc/network/interfaces`` file uses combination of IP address, network address, netmask and broadcast address to configure IPv4 network interface. We can get these values from a single 'host/prefix' combination: In Debian-based systems, the network configuration stored in the ``/etc/network/interfaces`` file uses a combination of IP address, network address, netmask and broadcast address to configure an IPv4 network interface. We can get these values from a single 'host/prefix' combination:
.. code-block:: jinja .. code-block:: jinja
@ -261,11 +263,13 @@ In Debian-based systems, network configuration stored in ``/etc/network/interfac
netmask 255.255.255.0 netmask 255.255.255.0
broadcast 192.0.2.255 broadcast 192.0.2.255
In above example, we needed to handle the fact that values were stored in In the above example, we needed to handle the fact that values were stored in
a list, which is unusual in IPv4 networks, where only single IP address can be a list, which is unusual in IPv4 networks, where only a single IP address can be
set on an interface. However, IPv6 networks can have multiple IP addresses set set on an interface. However, IPv6 networks can have multiple IP addresses set
on an interface:: on an interface::
.. code-block:: jinja
# Jinja2 template # Jinja2 template
iface eth0 inet6 static iface eth0 inet6 static
{% set ipv6_list = host_prefix | unique | ipv6('host/prefix') %} {% set ipv6_list = host_prefix | unique | ipv6('host/prefix') %}
@ -281,7 +285,7 @@ on an interface::
iface eth0 inet6 static iface eth0 inet6 static
address 2001:db8:deaf:be11::ef3/64 address 2001:db8:deaf:be11::ef3/64
If needed, you can extract subnet and prefix information from 'host/prefix' value:: If needed, you can extract subnet and prefix information from the 'host/prefix' value::
# {{ host_prefix | ipaddr('host/prefix') | ipaddr('subnet') }} # {{ host_prefix | ipaddr('host/prefix') | ipaddr('subnet') }}
['2001:db8:deaf:be11::/64', '192.0.2.0/24'] ['2001:db8:deaf:be11::/64', '192.0.2.0/24']
@ -292,7 +296,7 @@ If needed, you can extract subnet and prefix information from 'host/prefix' valu
Converting subnet masks to CIDR notation Converting subnet masks to CIDR notation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Given a subnet in the form of network address and subnet mask, it can be converted into CIDR notation using ``ipaddr()``. 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::
ansible_default_ipv4: { ansible_default_ipv4: {
address: "192.168.0.11", address: "192.168.0.11",
@ -307,12 +311,12 @@ Given a subnet in the form of network address and subnet mask, it can be convert
type: "ether" type: "ether"
} }
First concatenate network and netmask:: First concatenate the network and netmask::
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' '192.168.0.0/255.255.255.0'
This result can be canonicalised 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::
# {{ net_mask | ipaddr('prefix') }} # {{ net_mask | ipaddr('prefix') }}
'24' '24'
@ -339,7 +343,7 @@ Converting from IPv6 to IPv4 works very rarely::
# {{ test_list | ipv6('ipv4') }} # {{ test_list | ipv6('ipv4') }}
['0.0.0.1/32'] ['0.0.0.1/32']
But we can make double conversion if needed:: But we can make a double conversion if needed::
# {{ test_list | ipaddr('ipv6') | ipaddr('ipv4') }} # {{ test_list | ipaddr('ipv6') | ipaddr('ipv4') }}
['192.24.2.1/32', '0.0.0.1/32', '192.168.32.0/24'] ['192.24.2.1/32', '0.0.0.1/32', '192.168.32.0/24']
@ -362,17 +366,17 @@ You can convert IP addresses to PTR records::
0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.d.a.a.f.c.2.3.0.8.b.d.0.1.0.0.2.ip6.arpa. 0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.d.a.a.f.c.2.3.0.8.b.d.0.1.0.0.2.ip6.arpa.
Converting IPv4 address to 6to4 address Converting IPv4 address to a 6to4 address
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
`6to4`_ tunnel is a way to access IPv6 Internet from IPv4-only network. If you A `6to4`_ tunnel is a way to access the IPv6 Internet from an IPv4-only network. If you
have a public IPv4 address, you automatically can configure it's IPv6 have a public IPv4 address, you can automatically configure its IPv6
equivalent in ``2002::/16`` network range - after conversion you will gain equivalent in the ``2002::/16`` network range. After conversion you will gain
access to a ``2002:xxxx:xxxx::/48`` subnet which could be split into 65535 access to a ``2002:xxxx:xxxx::/48`` subnet which could be split into 65535
``/64`` subnets if needed. ``/64`` subnets if needed.
To convert your IPv4 address, just send it through ``'6to4'`` filter. It will To convert your IPv4 address, just send it through the ``'6to4'`` filter. It will
be automatically converted to a router address (with ``::1/48`` host address):: be automatically converted to a router address (with a ``::1/48`` host address)::
# {{ '193.0.2.0' | ipaddr('6to4') }} # {{ '193.0.2.0' | ipaddr('6to4') }}
2002:c100:0200::1/48 2002:c100:0200::1/48
@ -384,7 +388,7 @@ IP Math
.. versionadded:: 2.7 .. versionadded:: 2.7
``ipmath()`` filter can be used to do simple IP math/arithmetic. The ``ipmath()`` filter can be used to do simple IP math/arithmetic.
Here are a few simple examples:: Here are a few simple examples::
@ -405,15 +409,15 @@ Here are a few simple examples::
Subnet manipulation Subnet manipulation
^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^
``ipsubnet()`` filter can be used to manipulate network subnets in several ways. The ``ipsubnet()`` filter can be used to manipulate network subnets in several ways.
Here is some example IP address and subnet:: Here is an example IP address and subnet::
address = '192.168.144.5' address = '192.168.144.5'
subnet = '192.168.0.0/16' subnet = '192.168.0.0/16'
To check if a given string is a subnet, pass it through the filter without any To check if a given string is a subnet, pass it through the filter without any
arguments. If given string is an IP address, it will be converted into arguments. If the given string is an IP address, it will be converted into
a subnet:: a subnet::
# {{ address | ipsubnet }} # {{ address | ipsubnet }}
@ -422,15 +426,15 @@ a subnet::
# {{ subnet | ipsubnet }} # {{ subnet | ipsubnet }}
192.168.0.0/16 192.168.0.0/16
If you specify a subnet size as first parameter of ``ipsubnet()`` filter, and If you specify a subnet size as the first parameter of the ``ipsubnet()`` filter, and
subnet size is **smaller than current one**, you will get number of subnets 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::
# {{ subnet | ipsubnet(20) }} # {{ subnet | ipsubnet(20) }}
16 16
Second argument of ``ipsubnet()`` filter is an index number; by specifying it The second argument of the ``ipsubnet()`` filter is an index number; by specifying it
you can get new subnet with specified size:: you can get a new subnet with the specified size::
# First subnet # First subnet
# {{ subnet | ipsubnet(20, 0) }} # {{ subnet | ipsubnet(20, 0) }}
@ -449,8 +453,8 @@ you can get new subnet with specified size::
192.168.176.0/20 192.168.176.0/20
If you specify an IP address instead of a subnet, and give a subnet size as If you specify an IP address instead of a subnet, and give a subnet size as
a first argument, ``ipsubnet()`` filter will instead return biggest subnet that the first argument, the ``ipsubnet()`` filter will instead return the biggest subnet that
contains a given IP address:: contains that given IP address::
# {{ address | ipsubnet(20) }} # {{ address | ipsubnet(20) }}
192.168.128.0/20 192.168.128.0/20
@ -474,10 +478,10 @@ smaller subnets::
# {{ address | ipsubnet(18, -5) }} # {{ address | ipsubnet(18, -5) }}
192.168.144.0/27 192.168.144.0/27
By specifying an other subnet as a second argument, if the second subnet include By specifying another subnet as a second argument, if the second subnet includes
the first you can have the rank of the first subnet in the second :: the first, you can determine the rank of the first subnet in the second ::
# The rank of the ip in the subnet (the ip is the 36870nth /32 of the subnet) # The rank of the IP in the subnet (the IP is the 36870nth /32 of the subnet)
# {{ address | ipsubnet(subnet) }} # {{ address | ipsubnet(subnet) }}
36870 36870
@ -493,25 +497,25 @@ the first you can have the rank of the first subnet in the second ::
# {{ '192.168.144.16/30' | ipsubnet('192.168.144.0/24') }} # {{ '192.168.144.16/30' | ipsubnet('192.168.144.0/24') }}
5 5
If the secound subnet doesn't include the first it raise an error If the second subnet doesn't include the first subnet, the ``ipsubnet()`` filter raises an error.
You can use ``ipsubnet()`` filter with ``ipaddr()`` filter to for example split You can use the ``ipsubnet()`` filter with the ``ipaddr()`` filter to, for example, split
given ``/48`` prefix into smaller, ``/64`` subnets:: a given ``/48`` prefix into smaller ``/64`` subnets::
# {{ '193.0.2.0' | ipaddr('6to4') | ipsubnet(64, 58820) | ipaddr('1') }} # {{ '193.0.2.0' | ipaddr('6to4') | ipsubnet(64, 58820) | ipaddr('1') }}
2002:c100:200:e5c4::1/64 2002:c100:200:e5c4::1/64
Because of the size of IPv6 subnets, iteration over all of them to find the 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 correct one may take some time on slower computers, depending on the size
difference between subnets. difference between the subnets.
Subnet Merging Subnet Merging
^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^
.. versionadded:: 2.6 .. versionadded:: 2.6
The `cidr_merge` filter can be used to merge subnets or individual addresses The ``cidr_merge()`` filter can be used to merge subnets or individual addresses
into their minimal representation, collapsing overlapping subnets and merging into their minimal representation, collapsing overlapping subnets and merging
adjacent ones wherever possible:: adjacent ones wherever possible::
@ -533,7 +537,7 @@ subnet which contains all of the inputs::
MAC address filter MAC address filter
^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^
You can use ``hwaddr()`` filter to check if a given string is a MAC address or 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::
# Example MAC address # Example MAC address