From: Petr Špaček <petr.spacek@nic.cz>
Date: Mon, 6 Jan 2020 14:18:27 +0000 (+0100)
Subject: doc: move verbose() to logging section
X-Git-Tag: v5.0.0~8^2~33
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=b19e2e6cb94580fdf08027a8fab2443181f1f72b;p=thirdparty%2Fknot-resolver.git

doc: move verbose() to logging section
---

diff --git a/daemon/README.rst b/daemon/README.rst
index de29f9d18..a3f0e1ced 100644
--- a/daemon/README.rst
+++ b/daemon/README.rst
@@ -3,9 +3,36 @@
 TODO: Environment
 =================
 
-.. function:: verbose(true | false)
+.. function:: user(name, [group])
+
+   :param string name: user name
+   :param string group: group name (optional)
+   :return: boolean
+
+   Drop privileges and start running as given user (and group, if provided).
+
+   .. tip:: Note that you should bind to required network addresses before changing user. At the same time, you should open the cache **AFTER** you change the user (so it remains accessible). A good practice is to divide configuration in two parts:
+
+      .. code-block:: lua
+
+         -- privileged
+         net.listen('127.0.0.1')
+         net.listen('::1')
+         user('knot-resolver', 'netgrp')
+         -- unprivileged
+         cache.size = 100*MB
+
+   Example output:
+
+   .. code-block:: lua
+
+      > user('baduser')
+      invalid user name
+      > user('knot-resolver', 'netgrp')
+      true
+      > user('root')
+      Operation not permitted
 
-   :return: Toggle verbose logging.
 
 .. function:: mode('strict' | 'normal' | 'permissive')
 
@@ -29,6 +56,7 @@ TODO: Environment
         Unacceptable or missing glue records trigger resolution of names listed
         in NS records before following respective delegation.
 
+
 .. function:: reorder_RR([true | false])
 
    :param boolean value: New value for the option *(optional)*
@@ -37,36 +65,6 @@ TODO: Environment
    If set, resolver will vary the order of resource records within RR-sets.
    It is disabled by default.
 
-.. function:: user(name, [group])
-
-   :param string name: user name
-   :param string group: group name (optional)
-   :return: boolean
-
-   Drop privileges and run as given user (and group, if provided).
-
-   .. tip:: Note that you should bind to required network addresses before changing user. At the same time, you should open the cache **AFTER** you change the user (so it remains accessible). A good practice is to divide configuration in two parts:
-
-      .. code-block:: lua
-
-         -- privileged
-         net = { '127.0.0.1', '::1' }
-         -- unprivileged
-         cache.size = 100*MB
-         trust_anchors.add_file('root.key')
-
-   Example output:
-
-   .. code-block:: lua
-
-      > user('baduser')
-      invalid user name
-      > user('knot-resolver', 'netgrp')
-      true
-      > user('root')
-      Operation not permitted
-
-
 
 .. _`JSON-encoded`: http://json.org/example
 .. _`Learn Lua in 15 minutes`: http://tylerneylon.com/a/learn-lua/
diff --git a/doc/config.rst b/doc/config.rst
index 3ee0dd564..8a48d17f6 100644
--- a/doc/config.rst
+++ b/doc/config.rst
@@ -124,14 +124,33 @@ individual services for classic DNS, DoT and DoH from each other.
    	panic("Use kresd@dns*, kresd@tls* or kresd@doh* instance names")
    end
 
-.. include:: ../daemon/README.rst
-.. include:: ../daemon/bindings/modules.rst
+Logging, monitoring, diagnostics
+================================
+Knot Resolver logs to standard outputs, which is then captured by supervisor
+and sent to logging system for further processing.
+To read logs use commands usual for your distribution.
+E.g. on distributions using systemd-journald use command ``journalctl -u kresd@* -f``.
+
+During normal operation only errors and other very important events are logged,
+so by default logs from Knot Resolver should contain only couple lines a day.
+For debugging purposes it is possible to enable very verbose logging using
+:func:`verbose` function.
+
+.. function:: verbose([true | false])
+
+   :param: ``true`` to enable, ``false`` to disable verbose logging.
+   :return: boolean Current state of verbose logging.
+
+   Toggle global verbose logging. Use only for debugging purposes.
+   On busy systems vebose logging can produce several MB of logs per
+   second and will slow down operation.
+
+More fine-grained tools are available in following modules:
 
-Monitoring and diagnostics
-==========================
 .. contents::
    :depth: 1
    :local:
+
 .. include:: ../modules/nsid/README.rst
 .. include:: ../modules/graphite/README.rst
 .. include:: ../modules/dnstap/README.rst