summaryrefslogtreecommitdiffstats
path: root/modules/http/README.rst
diff options
context:
space:
mode:
Diffstat (limited to 'modules/http/README.rst')
-rw-r--r--modules/http/README.rst188
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..e2d1b99
--- /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 | :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 unecrypted 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')
+
+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'``)
+ 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 was configured using
+``doh`` kind in :func:`net.listen`. Its configuration (such as certificates)
+took 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 the verbose 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/