From: bert hubert <bert.hubert@netherlabs.nl>
Date: Mon, 30 Nov 2015 18:36:06 +0000 (+0100)
Subject: sortlist docs
X-Git-Tag: dnsdist-1.0.0-alpha1~164
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=ce88feaca3e6a393369ac2668984972e2837fe58;p=thirdparty%2Fpdns.git

sortlist docs
---

diff --git a/docs/markdown/recursor/settings.md b/docs/markdown/recursor/settings.md
index 8e6225d158..732c7c6d42 100644
--- a/docs/markdown/recursor/settings.md
+++ b/docs/markdown/recursor/settings.md
@@ -359,6 +359,51 @@ Some DNS errors occur rather frequently and are no cause for alarm.
 If set to a digit, logging is performed under this LOCAL facility. See
 [Logging](../common/logging.md#logging). Do not pass names like 'local0'!
 
+## `lua-config-file`
+* Filename
+* Available since 4.0.0
+
+If set, and Lua support is compiled in, this will load an additional configuration file
+for newer features and more complicated setups. Currently the only supported additional feature is:
+
+### `addSortList`
+Sortlist is a complicated feature which allows for the ordering of A and
+AAAA records in answers to be modified, optionally dependently on who is
+asking. Since clients frequently connect to the 'first' IP address they see,
+this can effectively allow you to make sure that user from, say 10.0.0.0/8
+also preferrably connect to servers in 10.0.0.0/8.
+
+The syntax consists of a netmask for which this ordering instruction
+applies, followed by a set of netmask (groups) which describe the desired
+ordering. So an ordering instruction of "1.0.0.0/8", "2.0.0.0/8" will put
+anything within 1/8 first, and anything in 2/8 second. Other IP addresses
+would follow behind the addresses sorted earlier.
+
+If netmasks are grouped, this means these get equal ordering.
+
+`addSortList()` is intended to exactly mirror the semantics of the BIND
+sortlist option, but the syntax is slightly different.
+
+As an example, the following BIND sortlist:
+
+```
+{ 17.50.0.0/16; {17.238.240.0/24; 17.138.149.200;
+{17.218.242.254; 17.218.252.254;}; 17.38.42.80;
+17.208.240.100; }; };
+```
+
+Gets transformed into:
+
+```
+addSortList("17.50.0.0/16", {"17.238.240.0/24", "17.138.149.200",
+{"17.218.242.254", "17.218.252.254"}, "17.38.42.80", 
+"17.208.240.100" })
+```
+
+In other words: each IP address is put within quotes, and are separated by
+commas instead of semicolons. For the rest everything is identical.
+
+
 ## `lua-dns-script`
 * Path
 * Default: unset