Create sections for reverse DNS functions

Documentation + examples for:
 - createReverse
 - createForward
 - createReverse6
 - createForward6

Plus minor changes for  'closest' to 'pickclosest'

diff --git a/docs/lua-records.rst b/docs/lua-records.rst
index 017b51ff2268d20953eadf14745b0d8d48851209..ab8c855a4831bb643e33e2b6ad002aa00c3d9aa6 100644 (file)
--- a/docs/lua-records.rst
+++ b/docs/lua-records.rst
@@ -188,7 +188,7 @@ Record creation functions
 
   Various options can be set in the ``options`` parameter:
 
-  - ``selector``: used to pick the IP address from list of viable candidates. Choices include 'closest', 'random', 'hashed'.
+  - ``selector``: used to pick the IP address from list of viable candidates. Choices include 'pickclosest', 'random', 'hashed'.
   - ``source``: Source IP address to check from
 
 
@@ -207,7 +207,7 @@ Record creation functions
 
   Various options can be set in the ``options`` parameter:
 
-  - ``selector``: used to pick the IP address from list of viable candidates. Choices include 'closest', 'random', 'hashed'.
+  - ``selector``: used to pick the IP address from list of viable candidates. Choices include 'pickclosest', 'random', 'hashed'.
   - ``source``: Source IP address to check from
   - ``stringmatch``: check ``url`` for this string, only declare 'up' if found
 
@@ -306,6 +306,144 @@ Record creation functions
 
   See :func:`pickwhashed` for an example.
 
+Reverse DNS functions
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. note::
+  **WARNING**: The reverse DNS functions are under active development. **They may**
+  **not be safe for production use.** The syntax of these functions may change at any
+  time.
+
+.. function:: createReverse(format)
+
+  Used for generating default hostnames from IPv4 wildcard reverse DNS records, e.g. *.0.0.127.in-addr.arpa 
+  
+  See :func:`createReverse6` for IPv6 records (ip6.arpa)
+  See :func:`createForward` for creating the A records to a wildcard record such as *.static.example.com
+  
+  Returns a formatted hostname based on the format string passed.
+
+  :param format: A hostname string to format, for example ``%1%.%2%.%3%.%4%.static.example.com``.
+  
+  Formatting options::
+   
+   - ``%1%`` to ``%4%`` are individual octets
+     - Example record query: ``1.0.0.127.in-addr.arpa``
+       - ``%1%`` = 127
+       - ``%2%`` = 0
+       - ``%3%`` = 0
+       - ``%4%`` = 1
+   - ``%5%`` joins the four decimal octets together with dashes
+     - Example: ``%5%.static.example.com`` is equivalent to ``%1%-%2%-%3%-%4%.static.example.com``
+   - ``%6%`` converts each octet from decimal to hexadecimal and joins them together
+     - Example: A query for ``15.0.0.127.static.example.com`` - ``%6`` would be `7f00000f` (127 is 7f, and 15 is 0f in hexadecimal)
+  
+  **NOTE:** At the current time, only forward dotted format works with :func:`createForward` (i.e. 127.0.0.1.static.example.com)
+  
+  Example records::
+  
+    *.0.0.127.in-addr.arpa IN    LUA    PTR "createReverse('%1%.%2%.%3%.%4%.static.example.com')"
+    *.1.0.127.in-addr.arpa IN    LUA    PTR "createReverse('%5%.static.example.com')"
+    *.2.0.127.in-addr.arpa IN    LUA    PTR "createReverse('%6%.static.example.com')"
+ 
+  When queried::
+  
+    # -x is syntactic sugar to request the PTR record for an IPv4/v6 address such as 127.0.0.5
+    # Equivalent to dig PTR 5.0.0.127.in-addr.arpa
+    $ dig +short -x 127.0.0.5 @ns1.example.com
+    127.0.0.5.static.example.com.
+    $ dig +short -x 127.0.1.5 @ns1.example.com
+    127-0-0-5.static.example.com.
+    $ dig +short -x 127.0.2.5 @ns1.example.com
+    7f000205.static.example.com.
+
+.. function:: createForward()
+  
+  Used to generate the reverse DNS domains made from :func:`createReverse`
+  
+  Generates an A record for a dotted or hexadecimal IPv4 domain (e.g. 127.0.0.1.static.example.com)
+  
+  It does not take any parameters, it simply interprets the zone record to find the IP address.
+  
+  An example record for zone ``static.example.com``::
+    
+    *.static.example.com    IN    LUA    A "createForward()"
+  
+  **NOTE:** At the current time, only forward dotted format works for this function (i.e. 127.0.0.1.static.example.com)
+  
+  When queried::
+  
+    $ dig +short A 127.0.0.5.static.example.com @ns1.example.com
+    127.0.0.5
+  
+.. function:: createReverse6(format)
+
+  Used for generating default hostnames from IPv6 wildcard reverse DNS records, e.g. *.1.0.0.2.ip6.arpa 
+  
+  **For simplicity purposes, only small sections of IPv6 rDNS domains are used in most parts of this guide,**
+  **as a full ip6.arpa record is around 80 characters long, e.g. ``1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.b.0.0.0.a.0.0.0.1.0.0.2.ip6.arpa``**
+  
+  See :func:`createReverse` for IPv4 records (in-addr.arpa)
+  See :func:`createForward6` for creating the AAAA records to a wildcard record such as *.static.example.com
+  
+  Returns a formatted hostname based on the format string passed.
+
+  :param format: A hostname string to format, for example ``%33%.static6.example.com``.
+  
+  Formatting options::
+   
+   - ``%1%`` to ``%32%`` are individual characters (nibbles)
+     - Example record query: ``1.0.0.2.ip6.arpa``
+       - ``%1%`` = 2
+       - ``%2%`` = 0
+       - ``%3%`` = 0
+       - ``%4%`` = 1
+   - ``%33%`` converts the compressed address format into a dashed format, e.g. ``2001:a::1`` to ``2001-a--1``
+   - ``%34%`` to ``%41%`` represent the 8 uncompressed 2-byte chunks
+     - Example: A query for 2001:a:b::123
+       - ``%34%`` - returns ``2001`` (chunk 1)
+       - ``%35%`` - returns ``000a`` (chunk 2)
+       - ``%41%`` - returns ``0123`` (chunk 8)
+  
+  **NOTE:** At the current time, only forward dotted format works with :func:`createForward` (i.e. 1.0.0.2.static.example.com)
+  
+  Example records::
+  
+    *.1.0.0.2.ip6.arpa IN    LUA    PTR "createReverse('%33%.static6.example.com')"
+    *.2.0.0.2.ip6.arpa IN    LUA    PTR "createReverse('%34%.%35%.static6.example.com')"
+ 
+  When queried::
+  
+    # -x is syntactic sugar to request the PTR record for an IPv4/v6 address such as 2001::1
+    # Equivalent to dig PTR 1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.b.0.0.0.a.0.0.0.1.0.0.2.ip6.arpa
+    # readable version:     1.0.0.0 .0.0.0.0 .0.0.0.0 .0.0.0.0 .0.0.0.0 .b.0.0.0 .a.0.0.0 .1.0.0.2 .ip6.arpa
+    
+    $ dig +short -x 2001:a:b::1 @ns1.example.com
+    2001-a-b--1.static6.example.com.
+    
+    $ dig +short -x 2002:a:b::1 @ns1.example.com
+    2002.000a.static6.example.com
+
+.. function:: createForward6()
+  
+  Used to generate the reverse DNS domains made from :func:`createReverse6`
+  
+  Generates an AAAA record for a dashed compressed IPv6 domain (e.g. 2001-a-b--1.static6.example.com)
+  
+  It does not take any parameters, it simply interprets the zone record to find the IP address.
+  
+  An example record for zone ``static.example.com``::
+    
+    *.static6.example.com    IN    LUA    AAAA "createForward6()"
+  
+  **NOTE:** At the current time, only dashed compressed format works for this function (i.e. 2001-a-b--1.static6.example.com)
+  
+  When queried::
+  
+    $ dig +short AAAA 2001-a-b--1.static6.example.com @ns1.example.com
+    2001:a:b::1
+
+
 Helper functions
 ~~~~~~~~~~~~~~~~