Commit 9f08e7f2 authored by Petr Špaček's avatar Petr Špaček

http: update docs

parent 1223599d
......@@ -60,6 +60,8 @@ machine.
ListenDatagram=[::1]:53000
ListenStream=[::1]:53000
.. _kresd-tls-socket-override-port:
The ``kresd-tls.socket`` can also be configured in the same way to listen for
TLS connections.
......
......@@ -107,11 +107,11 @@ for testing.
.. code-block:: bash
# Get current rule set
$ curl -s -X GET http://localhost:8053/daf | jq .
$ curl -s -X GET http://localhost:8453/daf | jq .
{}
# Create new rule
$ curl -s -X POST -d "src = 127.0.0.1 pass" http://localhost:8053/daf | jq .
$ curl -s -X POST -d "src = 127.0.0.1 pass" http://localhost:8453/daf | jq .
{
"count": 0,
"active": true,
......@@ -120,11 +120,11 @@ for testing.
}
# Disable rule
$ curl -s -X PATCH http://localhost:8053/daf/1/active/false | jq .
$ curl -s -X PATCH http://localhost:8453/daf/1/active/false | jq .
true
# Retrieve a rule information
$ curl -s -X GET http://localhost:8053/daf/1 | jq .
$ curl -s -X GET http://localhost:8453/daf/1 | jq .
{
"count": 4,
"active": true,
......@@ -133,5 +133,5 @@ for testing.
}
# Delete a rule
$ curl -s -X DELETE http://localhost:8053/daf/1 | jq .
$ curl -s -X DELETE http://localhost:8453/daf/1 | jq .
true
......@@ -3,10 +3,21 @@
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.
.. warning::
* DoH support was added in version 4.0.0 and is subject to change.
* DoH implementation in Knot Resolver is intended for experimentation
only as there is insufficient experience with the module
and the DoH protocol in general.
* For the time being it is recommended to run DoH endpoint
on a separate machine which is not handling normal DNS operations.
* More information about controversies around the DoH can be found
in blog posts
`DNS Privacy at IETF 104 <http://www.potaroo.net/ispcol/2019-04/angst.html>`_
and
`More DOH <http://www.potaroo.net/ispcol/2019-04/moredoh.html>`_
by Geoff Huston.
* 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.
......@@ -33,41 +44,18 @@ This integrated DoH server has following properties:
- 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 = '::', -- listen on ALL IPv4 and IPv6 addresses
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!
:ref:`Example configuration <mod-http-example>` is part of examples for generic
HTTP module. After configuring your endpoint you can reach the DoH endpoint using
URL ``https://your.resolver.hostname.example:44353/doh``, done!
.. code-block:: bash
# query for www.knot-resolver.cz AAAA
$ curl -k https://hostname.example/doh?dns=l1sBAAABAAAAAAAAA3d3dw1rbm90LXJlc29sdmVyAmN6AAAcAAE
$ curl -k https://your.resolver.hostname.example:44353/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:
Alternative configurations use HTTP proxies between clients and a Knot Resolver instance:
Normal HTTP proxy
^^^^^^^^^^^^^^^^^
......@@ -119,4 +107,12 @@ 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 <https://gist.github.com/bagder/5e29101079e9ac78920ba2fc718aceec>`_.
in article
`Inside Firefox’s DOH engine <https://daniel.haxx.se/blog/2018/06/03/inside-firefoxs-doh-engine/>`_
by Daniel Stenberg.
.. warning::
Please note that Knot Resolver developers are not as enthusiastic
about DoH technology as author of the article linked above,
make sure you read :ref:`warnings at beginning of this section <mod-http-doh>`.
This diff is collapsed.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment