From: Petr Špaček Date: Thu, 4 Apr 2019 16:25:09 +0000 (+0200) Subject: doh: add docs X-Git-Tag: v4.0.0~10^2~7 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=85ff42c22216533aa34d30b2471d8b01cc7134e1;p=thirdparty%2Fknot-resolver.git doh: add docs --- diff --git a/doc/modules.rst b/doc/modules.rst index 4209fed5f..23b20155f 100644 --- a/doc/modules.rst +++ b/doc/modules.rst @@ -14,6 +14,7 @@ Modules .. include:: ../modules/view/README.rst .. include:: ../modules/predict/README.rst .. include:: ../modules/http/README.rst +.. include:: ../modules/http/README.doh.rst .. include:: ../modules/daf/README.rst .. include:: ../modules/rebinding/README.rst .. include:: ../modules/graphite/README.rst diff --git a/modules/http/README.doh.rst b/modules/http/README.doh.rst new file mode 100644 index 000000000..8c35436a0 --- /dev/null +++ b/modules/http/README.doh.rst @@ -0,0 +1,122 @@ +.. _mod-http-doh: + +DNS-over-HTTP (DoH) +------------------- + +.. warning:: DoH support was added in version 4.0.0 and is subject to change. + Please note there is insufficient operational experience with + this module and the DoH protocol in general. + Knot Resolver developers do not endorse use of the DoH protocol. + +Following section compares several options for running a DoH capable server. +Make sure you read through this chapter before exposing the DoH service to users. + +DoH support in Knot Resolver +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The :ref:`HTTP module ` in Knot Resolver also provides support for +binary DNS-over-HTTP protocol standardized in :rfc:`8484`. + +This integrated DoH server has following properties: + +:Scenario: + HTTP module in Knot Resolver configured to provide ``/doh`` endpoint + (as shown below). + +:Advantages: + - Integrated solution provides management and monitoring in one place. + - Supports ACLs for DNS traffic based on client's IP address. + +:Disadvantages: + - Exposes Knot Resolver instance to attacks over HTTP. + - Does not offer fine grained authorization and logging at HTTP level. + - Let's Encrypt integration is not automated. + + +.. note:: For the time being it is recommended to run DoH endpoint + on a separate machine which is not handling normal DNS operations. + +Example configuration: + +.. code-block:: lua + + -- Load HTTP module with defaults + modules.load('http') + http.config({ + host = 'hostname.example', -- change to your server name + port = 443, -- feel free to use any other port + tls = true, + -- use valid X.509 cert issued by a recognized Certificate authority + cert = '/etc/knot-resolver/mycert.crt', + key = '/etc/knot-resolver/mykey.key', + }) + + -- disable all HTTP endpoints except DoH + for endpoint, _ in pairs(http.endpoints) do + if endpoint ~= '/doh' then + http.endpoints[endpoint] = nil + end + end + +Now you can reach the DoH endpoint using URL ``https://hostname.example/doh``, done! + +.. code-block:: bash + + # query for www.knot-resolver.cz AAAA + $ curl -k https://hostname.example/doh?dns=l1sBAAABAAAAAAAAA3d3dw1rbm90LXJlc29sdmVyAmN6AAAcAAE + +Please see section :ref:`mod-http-tls` for further details about TLS configuration. + +Alternative configurations use HTTP proxies between clients and Knot Resolver instance: + +Normal HTTP proxy +^^^^^^^^^^^^^^^^^ +:Scenario: + A standard HTTP-compliant proxy is configured to proxy `GET` + and `POST` requests to HTTP endpoint `/doh` to a machine + running Knot Resolver. + +:Advantages: + - Protects Knot Resolver instance from + `some` types of attacks at HTTP level. + - Allows fine-grained filtering and logging at HTTP level. + - Let's Encrypt integration is readily available. + - Is based on mature software. + +:Disadvantages: + - Fine-grained ACLs for DNS traffic are not available because + proxy hides IP address of client sending DNS query. + - More complicated setup with two components (proxy + Knot Resolver). + +HTTP proxy with DoH support +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +:Scenario: + HTTP proxy extended with a + `special module for DNS-over-HTTP `_. + The module transforms HTTP requests to standard DNS queries + which are then processed by Knot Resolver. + DNS replies from Knot Resolver are then transformed back to HTTP + encoding by the proxy. + +:Advantages: + - Protects Knot Resolver instance from `all` attacks at HTTP level. + - Allows fine-grained filtering and logging at HTTP level. + - Let's Encrypt integration is readily available + if proxy is based on a standard HTTP software. + +:Disadvantages: + - Fine-grained ACLs for DNS traffic are not available because + proxy hides IP address of client sending DNS query. + (Unless proxy and resolver are using non-standard packet extensions like + `DNS X-Proxied-For `_.) + - More complicated setup with three components (proxy + special module + Knot Resolver). + +Client configuration +^^^^^^^^^^^^^^^^^^^^ +Most common client today is web browser Firefox. Relevant configuration is described e.g. in following +`article `_. +To use your own DoH server just change ``network.trr.uri`` configuration option +to match URL of your DoH endpoint. + +More detailed description of configuration options in Firefox can be found +`here `_. diff --git a/modules/http/README.rst b/modules/http/README.rst index 558fb86c4..38b95ea0e 100644 --- a/modules/http/README.rst +++ b/modules/http/README.rst @@ -48,6 +48,7 @@ Now you can reach the web services and APIs, done! $ curl -k https://localhost:8053 $ curl -k https://localhost:8053/stats +.. _mod-http-tls: Configuring TLS ^^^^^^^^^^^^^^^ @@ -97,6 +98,7 @@ The HTTP module has several built-in services to use. "``/stats``", "Statistics/metrics", "Exported metrics in JSON." "``/metrics``", "Prometheus metrics", "Exported metrics for Prometheus_" "``/trace/:name/:type``", "Tracking", "Trace resolution of the query and return the verbose logs." + "``/doh``", "DNS-over-HTTP", ":rfc:`8484` endpoint, see :ref:`mod-http-doh`." Enabling Prometheus metrics endpoint ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^