dnsdist: Document the Key Value Store objects and actions

diff --git a/pdns/dnsdistdist/docs/reference/index.rst b/pdns/dnsdistdist/docs/reference/index.rst
index 7f7f3ece426537c89332357f241bdca76d4a33b9..b541b3ae463279f32bf1b86e453486b3ea21cc05 100644 (file)
--- a/pdns/dnsdistdist/docs/reference/index.rst
+++ b/pdns/dnsdistdist/docs/reference/index.rst
@@ -20,3 +20,4 @@ These chapters contain extensive information on all functions and object availab
   carbon
   snmp
   tuning
+  kvs

diff --git a/pdns/dnsdistdist/docs/reference/kvs.rst b/pdns/dnsdistdist/docs/reference/kvs.rst
new file mode 100644 (file)
index 0000000..d88cc98
--- /dev/null
+++ b/pdns/dnsdistdist/docs/reference/kvs.rst
@@ -0,0 +1,114 @@
+Key Value Store functions and objects
+=====================================
+
+These are all the functions, objects and methods related to the CDB and LMDB key value stores.
+
+A lookup into a key value store can be done via the :func:`KeyValueStoreLookupAction` action,
+using the usual selectors to match the incoming queries for which the lookup should be done.
+
+The first step is to get a :ref:`KeyValueStore` object via one of the following functions:
+
+ * :func:`newCDBKVStore` for a CDB database ;
+ * :func:`newLMDBKVStore` for a LMDB one.
+
+Then the key used for the lookup can be selected via one of the following functions:
+
+ * the exact qname with :func:`KeyValueLookupKeyQName` ;
+ * a suffix match via :func:`KeyValueLookupKeySuffix`, meaning that several lookups will be done, removing one label from the qname at a time, until a match has been found or there is no label left ;
+ * the source IP with :func:`KeyValueLookupKeySourceIP` ;
+ * the value of an existing tag with :func:`KeyValueLookupKeyTag`.
+
+For example, to do a suffix-based lookup into a LMDB KVS database, the following rule can be used:
+
+  > kvs = newLMDBKVStore('/path/to/lmdb/database', 'database name')
+  > addAction(AllRule(), KeyValueStoreLookupAction(kvs, KeyValueLookupKeySuffix(), 'kvs-suffix-result'))
+
+For a query whose qname is "sub.domain.powerdns.com.", and for which only the "\8powerdns\3com\0" key exists in the database,
+this would result in the following lookups:
+
+ * \3sub\5domain\8powerdns\3com\0
+ * \5domain\8powerdns\3com\0
+ * \8powerdns\3com\0
+
+Then a match is found for the last key, and the corresponding value is stored into the 'kvs-suffix-result' tag. This tag can now be used in subsequent rules to take an action based on the result of the lookup.
+
+ > addAction(TagRule('kvs-suffix-result', 'this is the value obtained from the lookup'), SpoofAction('2001:db8::1'))
+
+If the value found in the LMDB database for the key '\8powerdns\3com\0' was 'this is the value obtained from the lookup', then the query is immediately answered with a AAAA record.
+
+
+.. class:: KeyValueStore
+
+  .. versionadded:: 1.5.0
+
+  Represents a Key Value Store
+
+  .. method:: KeyValueStore:lookup(key)
+
+    Does a lookup into the corresponding key value store, and return the result as a string.
+    The key is first parsed as a network address, and if that fails into a DNS name. If that also fails the raw string is used for the lookup.
+
+    :param string key: The key to look up
+
+  .. method:: KeyValueStore:lookupSuffix(key)
+
+    Does a suffix-based lookup into the corresponding key value store, and return the result as a string.
+    The key is parsed as a DNS name, and several lookups will be done, removing one label from the name at a time until a match has been found or there is no label left.
+
+    :param string key: The name to look up
+
+  .. method:: KeyValueStore:reload()
+
+    Reload the database if this is supported by the underlying store. As of 1.5.0, only CDB stores can be reloaded, and this method is a no-op for LMDB stores.
+
+
+.. function:: KeyValueLookupKeyQName() -> KeyValueLookupKey
+
+  .. versionadded:: 1.5.0
+
+  Return a new KeyValueLookupKey object that, when passed to :func:`KeyValueStoreLookupAction`, will return the qname of the query in DNS wire format.
+
+.. function:: KeyValueLookupKeySourceIP() -> KeyValueLookupKey
+
+  .. versionadded:: 1.5.0
+
+  Return a new KeyValueLookupKey object that, when passed to :func:`KeyValueStoreLookupAction`, will return the source IP of the client in network byte-order.
+
+.. function:: KeyValueLookupKeySuffix() -> KeyValueLookupKey
+
+  .. versionadded:: 1.5.0
+
+  Return a new KeyValueLookupKey object that, when passed to :func:`KeyValueStoreLookupAction`, will return a vector of keys based on the labels of the qname in DNS wire format.
+  For example if the qname is sub.domain.powerdns.com. the following keys will be returned:
+
+   * \3sub\5domain\8powerdns\3com\0
+   * \5domain\8powerdns\3com\0
+   * \8powerdns\3com\0
+   * \3com\0
+   * \0
+
+.. function:: KeyValueLookupKeyTag() -> KeyValueLookupKey
+
+  .. versionadded:: 1.5.0
+
+  Return a new KeyValueLookupKey object that, when passed to :func:`KeyValueStoreLookupAction`, will return the value of the corresponding tag for this query, if it exists.
+
+.. function:: newCDBKVStore(filename, refreshDelay) -> KeyValueStore
+
+  .. versionadded:: 1.5.0
+
+  Return a new KeyValueStore object associated to the corresponding CDB database. The modification time
+  of the CDB file will be checked every 'refrehDelay' second and the database re-opened if needed.
+
+  :param string filename: The path to an existing CDB database
+  :param int refreshDelays: The delay in seconds between two checks of the database modification time. 0 means disabled
+
+.. function:: newLMDBKVStore(filename, dbName) -> KeyValueStore
+
+  .. versionadded:: 1.5.0
+
+  Return a new KeyValueStore object associated to the corresponding LMDB database. The database must have been created
+  with the ``MDB_NOSUBDIR`` flag.
+
+  :param string filename: The path to an existing LMDB database created with ``MDB_NOSUBDIR``
+  :param string dbName: The name of the database to use

diff --git a/pdns/dnsdistdist/docs/rules-actions.rst b/pdns/dnsdistdist/docs/rules-actions.rst
index 3366d8da5fcad703cc7f42d78506c50c332acee2..6d807f7fd897c69e216b1552c8f348078e663fbb 100644 (file)
--- a/pdns/dnsdistdist/docs/rules-actions.rst
+++ b/pdns/dnsdistdist/docs/rules-actions.rst
@@ -957,6 +957,20 @@ The following actions exist.
   :param string body: The body of the HTTP response, or a URL if the status code is a redirect (3xx).
   :param string contentType: The HTTP Content-Type header to return for a 200 response, ignored otherwise. Default is ''application/dns-message''.
 
+.. function:: KeyValueStoreLookupAction(kvs, lookupKey, destinationTag)
+
+  .. versionadded:: 1.5.0
+
+  Does a lookup into the key value store referenced by 'kvs' using the key returned by 'lookupKey',
+  and storing the result if any into the tag named 'destinationTag'.
+  The store can be a CDB (:func:`newCDBKVStore`) or a LMDB database (:func:`newLMDBKVStore`).
+  The key can be based on the qname (:func:`KeyValueLookupKeyQName` and :func:`KeyValueLookupKeySuffix`),
+  source IP (:func:`KeyValueLookupKeySourceIP`) or the value of an existing tag (:func:`KeyValueLookupKeyTag`).
+
+  :param KeyValueStore kvs: The key value store to query
+  :param KeyValueLookupKey lookupKey: The key to use for the lookup
+  :param string destinationTag: The name of the tag to store the result into
+
 .. function:: LogAction([filename[, binary[, append[, buffered]]]])
 
   Log a line for each query, to the specified ``file`` if any, to the console (require verbose) otherwise.