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 KeyValueStoreLookupRule() rule or the 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 KeyValueStore object via one of the following functions:

Then the key used for the lookup can be selected via one of the following functions:

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\6domain\8powerdns\3com\0
  • \6domain\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. Note that the tag is also created when the key has not been found, but the content of the tag is empty.

> 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

New in version 1.4.0.

Represents a Key Value Store

:lookup(key[, wireFormat])

Does a lookup into the corresponding key value store, and return the result as a string. The key can be a ComboAddress obtained via the newCA(), a DNSName obtained via the newDNSName() function, or a raw string.

Parameters:
  • DNSName or string key (ComboAddress,) – The key to look up
  • wireFormat (bool) – If the key is DNSName, whether to use to do the lookup in wire format (default) or in plain text
:lookupSuffix(key[, minLabels[, wireFormat]])

Does a suffix-based lookup into the corresponding key value store, and return the result as a string. The key should be a DNSName object obtained via the newDNSName() function, 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. If minLabels is set to a value larger than 0 the lookup will only be done as long as there is at least minLabels remaining. For example if the initial domain is “sub.powerdns.com.” and minLabels is set to 2, lookups will only be done for “sub.powerdns.com.” and “powerdns.com.”.

Parameters:
  • key (DNSName) – The name to look up
  • minLabels (int) – The minimum number of labels to do a lookup for. Default is 0 which means unlimited
  • wireFormat (bool) – Whether to do the lookup in wire format (default) or in plain text
:reload()

Reload the database if this is supported by the underlying store. As of 1.4.0, only CDB stores can be reloaded, and this method is a no-op for LMDB stores.

KeyValueLookupKeyQName([wireFormat]) → KeyValueLookupKey

New in version 1.4.0.

Return a new KeyValueLookupKey object that, when passed to KeyValueStoreLookupAction() or KeyValueStoreLookupRule(), will return the qname of the query in DNS wire format.

Parameters:wireFormat (bool) – Whether to do the lookup in wire format (default) or in plain text
KeyValueLookupKeySourceIP([v4mask[, v6mask]]) → KeyValueLookupKey

New in version 1.4.0.

Changed in version 1.5.0: Optional parameters v4mask and v6mask added.

Changed in version 1.7.0: Optional parameter includePort added.

Return a new KeyValueLookupKey object that, when passed to KeyValueStoreLookupAction() or KeyValueStoreLookupRule(), will return the source IP of the client in network byte-order.

Parameters:
  • v4mask (int) – Mask applied to IPv4 addresses. Default is 32 (the whole address)
  • v6mask (int) – Mask applied to IPv6 addresses. Default is 128 (the whole address)
  • includePort (int) – Whether to append the port (in network byte-order) after the address. Default is false
KeyValueLookupKeySuffix([minLabels[, wireFormat]]) → KeyValueLookupKey

New in version 1.4.0.

Return a new KeyValueLookupKey object that, when passed to KeyValueStoreLookupAction() or KeyValueStoreLookupRule(), will return a vector of keys based on the labels of the qname in DNS wire format or plain text. For example if the qname is sub.domain.powerdns.com. the following keys will be returned:

  • \3sub\6domain\8powerdns\3com\0
  • \6domain\8powerdns\3com\0
  • \8powerdns\3com\0
  • \3com\0
  • \0

If minLabels is set to a value larger than 0 the lookup will only be done as long as there is at least minLabels remaining. Taking back our previous example, it means only the following keys will be returned if minLabels is set to 2;

  • \3sub\6domain\8powerdns\3com\0
  • \6domain\8powerdns\3com\0
  • \8powerdns\3com\0
Parameters:
  • minLabels (int) – The minimum number of labels to do a lookup for. Default is 0 which means unlimited
  • wireFormat (bool) – Whether to do the lookup in wire format (default) or in plain text
KeyValueLookupKeyTag(tagName) → KeyValueLookupKey

New in version 1.4.0.

Return a new KeyValueLookupKey object that, when passed to KeyValueStoreLookupAction(), will return the value of the corresponding tag for this query, if it exists.

Parameters:tagName (str) – The name of the tag.
newCDBKVStore(filename, refreshDelay) → KeyValueStore

New in version 1.4.0.

Return a new KeyValueStore object associated to the corresponding CDB database. The modification time of the CDB file will be checked every ‘refreshDelay’ second and the database re-opened if needed.

Parameters:
  • filename (string) – The path to an existing CDB database
  • refreshDelays (int) – The delay in seconds between two checks of the database modification time. 0 means disabled
newLMDBKVStore(filename, dbName[, noLock]) → KeyValueStore

New in version 1.4.0.

Changed in version 1.7.0: Added the optional parameter noLock.

Return a new KeyValueStore object associated to the corresponding LMDB database. The database must have been created with the MDB_NOSUBDIR flag. Since 1.7.0, the database is opened with the MDB_READONLY flag, and optionally with MDB_NOLOCK if noLock is set to true.

Parameters:
  • filename (string) – The path to an existing LMDB database created with MDB_NOSUBDIR
  • dbName (string) – The name of the database to use
  • noLock (bool) – Whether to open the database with the MDB_NOLOCK flag. Default is false