Lua library containing a dns client, several utilities, and a load-balancer.

The module is currently OpenResty only, and builds on top of the `lua-resty-dns` library


  • resolves A, AAAA, CNAME and SRV records, including port

  • parses /etc/hosts

  • parses /resolv.conf and applies LOCALDOMAIN and RES_OPTIONS variables

  • caches dns query results in memory

  • synchronizes requests (a single request for many requestors, eg. when cached ttl expires under heavy load)

  • toip applies a local (weighted) round-robin scheme on the query results

  • ring-balancer for round-robin and consistent-hashing approaches

Copyright and license

Copyright: (c) 2016-2018 Kong, Inc.

Author: Thijs Schreijer

License: Apache 2.0


Tests are executed using busted, but because they run inside the resty cli tool, you must use the rbusted script.


Versioning is strictly based on Semantic Versioning

2.2.0 (28-Aug-2018) Fixes and a new option

  • Added: a new option validTtl that, if set, will forcefully override the ttl value of any valid answer received. Issue 48.

  • Fix: remove multiline log entries, now encoded as single-line json. Issue 52.

  • Fix: always inject a localhost value, even if not in /etc/hosts. Issue 54.

  • Fix: added a workaround for Amazon Route 53 nameservers replying with a ttl=0 whilst the record has a non-0 ttl. Issue 56.

2.1.0 (21-May-2018) Fixes

  • Fix: the round robin scheme for the balanceer starts at a randomized position to prevent all workers from starting with the same peer.

  • Fix: the balancer no longer returns port = 0 for SRV records without a port, the default port is now returned.

  • Fix: ipv6 nameservers with a scope in their address are not supported. This fix will simply skip them instead of throwing errors upon resolving. Fixes issue 43.

  • Minor: improved logging in the balancer

  • Minor: relax requery default interval for failed dns queries from 1 to 30 seconds.

2.0.0 (22-Feb-2018) Major performance improvement (balancer) and bugfixes

  • BREAKING: improved performance and memory footprint for large balancers. 80-85% less memory will be used, while creation time dropped by 85-90%. Since the host:getPeer() function signature changed, this is a breaking change.

  • Change: BREAKING the errors for cache-only lookup failures and empty records have been changed.

  • Fix: do not fail initialization without nameservers.

  • Fix: properly recognize IPv6 in square brackets from the /etc/hosts file.

  • Fix: do not set success-type to types we're not looking for. Fixes Kong issue #3210.

  • Fix: store records from the additional section in cache

  • Fix: do not overwrite stale data in the client cache with empty records

1.0.0 (14-Dec-2017) Fixes and IPv6

  • Change: BREAKING all IPv6 addresses are now returned with square brackets

  • Fix: properly recognize IPv6 addresses in square brackets

0.6.3 (27-Nov-2017) Fixes and flagging unhealthy peers

  • Added: flag to mark an address as failed/unhealthy, see setPeerStatus

  • Added: callback to receive balancer updates; addresses added-to/removed-from the balancer (after DNS updates for example).

  • fix: SRV record entries with a weight 0 are now supported

  • fix: failure of the last hostname to resolve (balancer)

0.6.2 (04-Sep-2017) Fixes and refactor

  • Fix: balancer not returning hostname for named SRV entries. See issue #17

  • Fix: fix an occasionally failing test

  • Refactor: remove metadata from the records, instead store it in its own cache

0.6.1 (28-Jul-2017) Randomization adjusted

  • Change: use a different randomizer for the ring-balancer to predictably recreate the balancer in the exact same state (adds the lrandom library as a new dependency)

0.6.0 (14-Jun-2017) Rewritten resolver core to resolve async

  • Added: resolution will be done async whenever possible. For this to work a new setting has been introduced staleTtl which determines for how long stale records will returned while a query is in progress in the background.

  • Change: BREAKING! several functions that previously returned and took a resolver object no longer do so.

  • Fix: no longer lookup ip adresses as names if the query type is not A or AAAA

  • Fix: normalize names to lowercase after query

  • Fix: set last-success types for hosts-file entries and ip-addresses

0.5.0 (25-Apr-2017) implement SEARCH and NDOTS

  • Removed: BREAKING! stdError function removed.

  • Added: implemented the search and ndots options.

  • Change: resolve no longer returns empty results or dns errors as a table but as lua errors (nil + error).

  • Change: toip() and resolve() have an extra result; history. A table with the list of tried names/types/results.

  • Fix: timeout and retrans options from resolv.conf were ignored by the client module.

  • Fix: nameservers with an ipv6 address would not be used properly. Also added a flag enable_ipv6 (default == false) to enable the useage of ipv6 nameservers.

0.4.1 (21-Apr-2017) Bugfix

  • Fix: cname record caching causing excessive dns queries, see Kong issue #2303.

0.4.0 (30-Mar-2017) Bugfixes

  • Change: BREAKING! modified hash treatment, must now be an integer > 0

  • Added: BREAKING! a retry counter to fall-through on hashed-retries (changes the getpeer signature)

  • Fix: the MAXNS (3) was not honoured, so more than 3 nameservers would be parsed from the resolv.conf file. Fixes Kong issue #2290.

  • Added: two convenience hash functions

  • Performance: some improvements (pre-allocated tables for the slot lists)

0.3.2 (6-Mar-2017) Bugfixes

  • Fix: Cleanup disabled addresses but did not delete them, causing errors when they were repeatedly added/removed

  • Fix: potential racecondition when re-querying dns records

  • Fix: potential memoryleak when a balancer object was released with a running timer

0.3.1 (22-Feb-2017) Bugfixes

  • Kubernetes dns returns an SRV record for individual nodes, where the target is the same name again (hence causing a recursive loop). Now those entries will be removed, and if nothing is left, it will fail the SRV lookup, causing a fall-through to the next record type.

  • Kubernetes tends to return a port of 0 if none is provided/set, hence the toip() function now ignores a port=0 and falls back on the port passed in.

0.3.0 (8-Nov-2016) Major breaking update

  • breaking: renamed a lot of things; method names, module names, etc. pretty much breaks everything... also releasing under a new name

  • feature: udp function setpeername added (client)

  • fix: do not synchronize dns queries for ttl=0 requests (client)

  • fix: full test coverage and accompanying fixes (ring-balancer)

  • feature: auto-retry for failed dns queries (ring-balancer)

  • feature: updating weights is now supported without removing/re-adding (ring-balancer)

  • change: auto-retry interval configurable for failed dns queries (ring-balancer)

  • change: max life-time interval configurable for ttl=0 dns records (ring-balancer)

0.2.1 (24-Oct-2016) Bugfix

  • fix: toip() failed on SRV records with only 1 entry

0.2 (18-Oct-2016) Added the balancer

  • fix: was creating resolver objects even if serving from cache

  • change: change resolver order (SRV is now first by default) for dns servers that create both SRV and A records for each entry

  • feature: make resolver order configurable

  • feature: ring-balancer (experimental, no full test coverage yet)

  • other: more test coverage for the dns client

0.1 (09-Sep-2016) Initial released version