diff --git a/docs/features/dns-cache.rst b/docs/features/dns-cache.rst
new file mode 100644
index 0000000000000000000000000000000000000000..0a42e11041f6b9002f2b44a01f8fa3f46ececf86
--- /dev/null
+++ b/docs/features/dns-cache.rst
@@ -0,0 +1,52 @@
+DNS caching
+===========
+
+User experience may be greatly improved when dns is accelerated. Also, it
+seems like a good idea to keep the number of packages being exchanged
+between node and gateway as small as possible. In order to do this, a
+DNS cache may be used on a node. The dnsmasq instance listening on port
+53 on the node will be reconfigured to answer requests, use a list of
+upstream servers and a specific cache size if the options listed below are
+added to site.conf. Upstream servers are the DNS servers which are normally
+used by the nodes to resolve hostnames (e.g. gateways/supernodes).
+
+There are the following settings:
+ servers
+ cacheentries
+
+To use the node's DNS server, both options should be set. The node will cache at
+most 'cacheentries' many DNS records in RAM. The 'servers' list will be used to
+resolve the received DNS queries if the request cannot be answered from
+cache. Gateways should announce the "next node" address via DHCP and RDNSS (if
+any). Note that not setting 'servers' here will lead to DNS not working: Once
+the gateways all announce the "next node" address for DNS, there is no way for
+nodes to automatically determine DNS servers. They have to be baked into the
+firmware.
+
+If these settings do not exist, the cache is not initialized and RAM usage will
+not increase.
+
+When next_node.name is set, an A record and an AAAA record for the
+next-node IP address are placed in the dnsmasq configuration. This means that
+the content of next_node.name may be resolved even without upstream connectivity.
+It is suggested to use the same name as the DNS server provides:
+e.g. nextnode.location.community.example.org (This way the name also works if a
+client uses static DNS Servers). Hint: If next_node.name does not contain a dot
+some browsers would open the searchpage instead.
+
+::
+
+ dns = {
+ cacheentries = 5000,
+ servers = { '2001:db8::1', },
+ },
+
+ next_node = {
+ name = { 'nextnode.location.community.example.org', 'nextnode', 'nn' },
+ ip6 = '2001:db8:8::1',
+ ip4 = '198.51.100.1',
+ }
+
+
+The cache will be initialized during startup.
+Each cache entry will occupy about 90 bytes of RAM.
diff --git a/docs/features/dns-forwarder.rst b/docs/features/dns-forwarder.rst
deleted file mode 100644
index d74f9618fe3fafd6ba8467e4425f154880e5fdb7..0000000000000000000000000000000000000000
--- a/docs/features/dns-forwarder.rst
+++ /dev/null
@@ -1,26 +0,0 @@
-DNS forwarder
-=============
-
-A Gluon node can be configured to act as a DNS forwarder. Requests for the
-next-node hostname(s) can be answered locally, without querying the upstream
-resolver.
-
-**Note:** While this reduces answer time and allows to use the next-node
-hostname without upstream connectivity, this feature should not be used for
-next-node hostnames that are FQDN when the zone uses DNSSEC.
-
-One or more upstream resolvers can be configured in the *dns.servers* setting.
-When *next_node.name* is set, A and/or AAAA records for the next-node IP
-addresses are placed in the dnsmasq configuration.
-
-::
-
- dns = {
- servers = { '2001:db8::1', },
- },
-
- next_node = {
- name = { 'nextnode.location.community.example.org', 'nextnode', 'nn' },
- ip6 = '2001:db8:8::1',
- ip4 = '198.51.100.1',
- }
diff --git a/docs/index.rst b/docs/index.rst
index c9bcbdb30e50a3855d6f6b48c8efc60b2ed5fbf0..99fc8535f7d5d4df390c57d2156b8ff9f342e632 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -25,7 +25,7 @@ Several Freifunk communities in Germany use Gluon as the foundation of their Fre
features/wlan-configuration
features/private-wlan
features/wired-mesh
- features/dns-forwarder
+ features/dns-cache
features/monitoring
features/multidomain
features/authorized-keys
diff --git a/docs/releases/v2017.1.rst b/docs/releases/v2017.1.rst
index 9e8e72c9c0fa76fa40f12d95f9960f4e39552d6a..5319aae3c0534f0956c2edb19438d46e0b1cce5e 100644
--- a/docs/releases/v2017.1.rst
+++ b/docs/releases/v2017.1.rst
@@ -88,6 +88,8 @@ New features
* Add support for making nodes a DNS cache for clients
(`#1000 <https://github.com/freifunk-gluon/gluon/pull/1000>`_)
+ See also: :doc:`../features/dns-cache`
+
* Add L2TP via tunneldigger as an alternative VPN system
(`#978 <https://github.com/freifunk-gluon/gluon/pull/978>`_)
diff --git a/package/gluon-core/check_site.lua b/package/gluon-core/check_site.lua
index 103cb929da8304c8ae4f1bd2afcc10713678b332..06b9ac59d0e32348184a197b4f193e195051d599 100644
--- a/package/gluon-core/check_site.lua
+++ b/package/gluon-core/check_site.lua
@@ -66,6 +66,7 @@ need_boolean(in_site({'poe_passthrough'}), false)
if need_table({'dns'}, nil, false) then
need_string_array_match({'dns', 'servers'}, '^[%x:]+$')
+ need_number({'dns', 'cacheentries'}, false)
end
need_string_array(in_domain({'next_node', 'name'}), false)
diff --git a/package/gluon-core/luasrc/lib/gluon/upgrade/820-dns-config b/package/gluon-core/luasrc/lib/gluon/upgrade/820-dns-config
index f3fdfbff7bbf08c8ed4bd0e4b1cf60ea1c732503..0db663013403fccff067e052e606c51fd7f73654 100755
--- a/package/gluon-core/luasrc/lib/gluon/upgrade/820-dns-config
+++ b/package/gluon-core/luasrc/lib/gluon/upgrade/820-dns-config
@@ -12,7 +12,7 @@ uci:set('dhcp', dnsmasq, 'localise_queries', true)
uci:set('dhcp', dnsmasq, 'localservice', false)
uci:set('dhcp', dnsmasq, 'server', dns.servers)
-uci:delete('dhcp', dnsmasq, 'cachesize')
+uci:set('dhcp', dnsmasq, 'cachesize', dns.cacheentries)
uci:delete('firewall', 'client_dns')
if dns.servers then