diff options
Diffstat (limited to 'modules/http/README.rst')
| -rw-r--r-- | modules/http/README.rst | 188 |
1 files changed, 188 insertions, 0 deletions
diff --git a/modules/http/README.rst b/modules/http/README.rst new file mode 100644 index 0000000..6d8a075 --- /dev/null +++ b/modules/http/README.rst @@ -0,0 +1,188 @@ +.. SPDX-License-Identifier: GPL-3.0-or-later + +.. _mod-http: + +Other HTTP services +=================== + +.. tip:: In most distributions, the ``http`` module is available from a + separate package ``knot-resolver-module-http``. The module isn't packaged + for openSUSE. + +This module does the heavy lifting to provide an HTTP and HTTP/2 enabled +server which provides few built-in services and also allows other +modules to export restful APIs and websocket streams. + +One example is statistics module that can stream live metrics on the website, +or publish metrics on request for Prometheus scraper. + +By default this module provides two kinds of endpoints, +and unlimited number of "used-defined kinds" can be added in configuration. + ++--------------+---------------------------------------------------------------------------------+ +| **Kind** | **Explanation** | ++--------------+---------------------------------------------------------------------------------+ +| webmgmt | :ref:`built-in web management <mod-http-built-in-services>` APIs (includes DoH) | ++--------------+---------------------------------------------------------------------------------+ +| doh_legacy | :ref:`mod-http-doh` | ++--------------+---------------------------------------------------------------------------------+ + +Each network address and port combination can be configured to expose +one kind of endpoint. This is done using the same mechanisms as +network configuration for plain DNS and DNS-over-TLS, +see chapter :ref:`network-configuration` for more details. + +.. warning:: Management endpoint (``webmgmt``) must not be directly exposed + to untrusted parties. Use `reverse-proxy`_ like Apache_ + or Nginx_ if you need to authenticate API clients + for the management API. + +By default all endpoints share the same configuration for TLS certificates etc. +This can be changed using ``http.config()`` configuration call explained below. + +.. _mod-http-example: + +Example configuration +--------------------- + +This section shows how to configure HTTP module itself. For information how +to configure HTTP server's IP addresses and ports please see chapter +:ref:`network-configuration`. + +.. code-block:: lua + + -- load HTTP module with defaults (self-signed TLS cert) + modules.load('http') + -- optionally load geoIP database for server map + http.config({ + geoip = 'GeoLite2-City.mmdb', + -- e.g. https://dev.maxmind.com/geoip/geoip2/geolite2/ + -- and install mmdblua library + }) + +Now you can reach the web services and APIs, done! + +.. code-block:: bash + + $ curl -k https://localhost:8453 + $ curl -k https://localhost:8453/stats + +.. _mod-http-tls: + +HTTPS (TLS for HTTP) +-------------------- + +By default, the web interface starts HTTPS/2 on specified port using an ephemeral +TLS certificate that is valid for 90 days and is automatically renewed. It is of +course self-signed. Why not use something like +`Let's Encrypt <https://letsencrypt.org>`_? + +.. warning:: + + If you use package ``luaossl < 20181207``, intermediate certificate is not sent to clients, + which may cause problems with validating the connection in some cases. + +You can disable unencrypted HTTP and enforce HTTPS by passing +``tls = true`` option for all HTTP endpoints: + +.. code-block:: lua + + http.config({ + tls = true, + }) + +It is also possible to provide different configuration for each +kind of endpoint, e.g. to enforce TLS and use custom certificate only for DoH: + +.. code-block:: lua + + http.config({ + tls = true, + cert = '/etc/knot-resolver/mycert.crt', + key = '/etc/knot-resolver/mykey.key', + }, 'doh_legacy') + +The format of both certificate and key is expected to be PEM, e.g. equivalent to +the outputs of following: + +.. code-block:: bash + + openssl ecparam -genkey -name prime256v1 -out mykey.key + openssl req -new -key mykey.key -out csr.pem + openssl req -x509 -days 90 -key mykey.key -in csr.pem -out mycert.crt + +It is also possible to disable HTTPS altogether by passing ``tls = false`` option. +Plain HTTP gets handy if you want to use `reverse-proxy`_ like Apache_ or Nginx_ +for authentication to API etc. +(Unencrypted HTTP could be fine for localhost tests as, for example, +Safari doesn't allow WebSockets over HTTPS with a self-signed certificate. +Major drawback is that current browsers won't do HTTP/2 over insecure connection.) + +.. warning:: + + If you use multiple Knot Resolver instances with these automatically maintained ephemeral certificates, + they currently won't be shared. + It's assumed that you don't want a self-signed certificate for serious deployments anyway. + +.. _mod-http-doh: + +Legacy DNS-over-HTTPS (DoH) +--------------------------- + +.. warning:: The legacy DoH implementation using ``http`` module (``kind='doh_legacy'``) + is deprecated. It has known performance and stability issues that won't be fixed. + Use new :ref:`dns-over-https` implementation instead. + +This was an experimental implementation of :rfc:`8484`. It can be configured using +``doh_legacy`` kind in :func:`net.listen`. Its configuration (such as certificates) +takes place in ``http.config()``. + +Queries were served on ``/doh`` and ``/dns-query`` endpoints. + +.. _mod-http-built-in-services: + +Built-in services +----------------- + +The HTTP module has several built-in services to use. + +.. csv-table:: + :header: "Endpoint", "Service", "Description" + + "``/stats``", "Statistics/metrics", "Exported :ref:`metrics <mod-stats-list>` from :ref:`mod-stats` in JSON format." + "``/metrics``", "Prometheus metrics", "Exported metrics for Prometheus_." + "``/trace/:name/:type``", "Tracking", ":ref:`Trace resolution <mod-http-trace>` of a DNS query and return its debug-level logs." + "``/doh``", "Legacy DNS-over-HTTPS", ":rfc:`8484` endpoint, see :ref:`mod-http-doh`." + "``/dns-query``", "Legacy DNS-over-HTTPS", ":rfc:`8484` endpoint, see :ref:`mod-http-doh`." + +Dependencies +------------ + +* `lua-http <https://github.com/daurnimator/lua-http>`_ (>= 0.3) available in LuaRocks + + If you're installing via Homebrew on OS X, you need OpenSSL too. + + .. code-block:: bash + + $ brew update + $ brew install openssl + $ brew link openssl --force # Override system OpenSSL + + Some other systems can install from LuaRocks directly: + + .. code-block:: bash + + $ luarocks --lua-version 5.1 install http + +* (*optional*) `mmdblua <https://github.com/daurnimator/mmdblua>`_ available in LuaRocks + + .. code-block:: bash + + $ luarocks --lua-version 5.1 install --server=https://luarocks.org/dev mmdblua + $ curl -O https://geolite.maxmind.com/download/geoip/database/GeoLite2-City.mmdb.gz + $ gzip -d GeoLite2-City.mmdb.gz + +.. _Prometheus: https://prometheus.io +.. _reverse-proxy: https://en.wikipedia.org/wiki/Reverse_proxy +.. _Apache: https://httpd.apache.org/docs/2.4/howto/reverse_proxy.html +.. _Nginx: https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/ |