1 files changed, 125 insertions, 0 deletions
diff --git a/src/knot/modules/dnsproxy/dnsproxy.rst b/src/knot/modules/dnsproxy/dnsproxy.rst
new file mode 100644
index 0000000..9493738
--- /dev/null
+++ b/src/knot/modules/dnsproxy/dnsproxy.rst
@@ -0,0 +1,125 @@
+.. _mod-dnsproxy:
+
+``dnsproxy`` – Tiny DNS proxy
+=============================
+
+The module forwards all queries, or all specific zone queries if configured
+per zone, to the indicated server for resolution. If configured in the fallback
+mode, only locally unsatisfied queries are forwarded. I.e. a tiny DNS proxy.
+There are several uses of this feature:
+
+* A substitute public-facing server in front of the real one
+* Local zones (poor man's "views"), rest is forwarded to the public-facing server
+* Using the fallback to forward queries to a resolver
+* etc.
+
+.. NOTE::
+   The module does not alter the query/response as the resolver would,
+   and the original transport protocol is kept as well.
+
+Example
+-------
+
+The configuration is straightforward and just a single remote server is
+required::
+
+   remote:
+     - id: hidden
+       address: 10.0.1.1
+
+   mod-dnsproxy:
+     - id: default
+       remote: hidden
+       fallback: on
+
+   template:
+     - id: default
+       global-module: mod-dnsproxy/default
+
+   zone:
+     - domain: local.zone
+
+When clients query for anything in the ``local.zone``, they will be
+responded to locally. The rest of the requests will be forwarded to the
+specified server (``10.0.1.1`` in this case).
+
+Module reference
+----------------
+
+::
+
+ mod-dnsproxy:
+   - id: STR
+     remote: remote_id
+     timeout: INT
+     address: ADDR[/INT] | ADDR-ADDR ...
+     fallback: BOOL
+     tcp-fastopen: BOOL
+     catch-nxdomain: BOOL
+
+.. _mod-dnsproxy_id:
+
+id
+..
+
+A module identifier.
+
+.. _mod-dnsproxy_remote:
+
+remote
+......
+
+A :ref:`reference<remote_id>` to a remote server where the queries are
+forwarded to.
+
+*Required*
+
+.. _mod-dnsproxy_timeout:
+
+timeout
+.......
+
+A remote response timeout in milliseconds.
+
+*Default:* ``500`` (milliseconds)
+
+.. _mod-dnsproxy_address:
+
+address
+.......
+
+An optional list of allowed ranges and/or subnets for query's source address.
+If the query's address does not fall into any of the configured ranges, the
+query isn't forwarded.
+
+*Default:* not set
+
+.. _mod-dnsproxy_fallback:
+
+fallback
+........
+
+If enabled, locally unsatisfied queries leading to REFUSED (no zone) are forwarded.
+If disabled, all queries are directly forwarded without any local attempts
+to resolve them.
+
+*Default:* ``on``
+
+.. _mod-dnsproxy_tcp-fastopen:
+
+tcp-fastopen
+............
+
+If enabled, TCP Fast Open is used when forwarding TCP queries.
+
+*Default:* ``off``
+
+.. _mod-dnsproxy_catch-nxdomain:
+
+catch-nxdomain
+..............
+
+If enabled, locally unsatisfied queries leading to NXDOMAIN are forwarded.
+This option is only relevant in the fallback mode.
+
+*Default:* ``off``