Merge pull request #7677 from rgacogne/dnsdist-logging-facility

[thirdparty/pdns.git] / docs / settings.rst

diff --git a/docs/settings.rst b/docs/settings.rst
index cede93eb01688db87bc74977fc7eca080c6d01c0..eab1244d270046cbe771b179dcf3c2b2f772292c 100644 (file)
--- a/docs/settings.rst
+++ b/docs/settings.rst
@@ -154,6 +154,8 @@ Static pre-shared authentication key for access to the REST API.
 -  Default: no
 
 .. versionadded:: 4.0.0
+.. versionchanged:: 4.2.0
+This setting has been removed in 4.2.0.
 
 Disallow data modification through the REST API when set.
 
@@ -228,7 +230,9 @@ See :ref:`metricscarbon`
 
 Send all available metrics to this server via the carbon protocol, which
 is used by graphite and metronome. It has to be an address (no
-hostnames). You may specify an alternate port by appending :port, ex:
+hostnames). Moreover you can specify more than one server using a comma delimited list, ex:
+carbon-server=10.10.10.10,10.10.10.20.
+You may specify an alternate port by appending :port, ex:
 127.0.0.1:2004. See :ref:`metricscarbon`.
 
 .. _setting-carbon-interval:
@@ -1144,13 +1148,13 @@ To notify all IP addresses apart from the 192.168.0.0/24 subnet use the followin
   :ref:`metadata-also-notify` domain metadata to avoid this potential bottleneck.
 
 .. note::
-  If your slaves support Internet Protocol version, which your master does not, 
-  then set ``only-notify`` to include only supported protocol version. 
+  If your slaves support Internet Protocol version, which your master does not,
+  then set ``only-notify`` to include only supported protocol version.
   Otherwise there will be error trying to resolve address.
-  
-  For example, slaves support both IPv4 and IPv6, but PowerDNS master have only IPv4, 
+
+  For example, slaves support both IPv4 and IPv6, but PowerDNS master have only IPv4,
   so allow only IPv4 with ``only-notify``::
-  
+
     only-notify=0.0.0.0/0
 
 .. _setting-out-of-zone-additional-processing:
@@ -1611,6 +1615,47 @@ IP Address for webserver/API to listen on.
 
 Webserver/API access is only allowed from these subnets.
 
+.. _setting-webserver-loglevel:
+
+``webserver-loglevel``
+----------------------
+.. versionadded:: 4.2.0
+
+-  String, one of "none", "normal", "detailed"
+
+The amount of logging the webserver must do. "none" means no useful webserver information will be logged.
+When set to "normal", the webserver will log a line per request that should be familiar::
+
+  [webserver] e235780e-a5cf-415e-9326-9d33383e739e 127.0.0.1:55376 "GET /api/v1/servers/localhost/bla HTTP/1.1" 404 196
+
+When set to "detailed", all information about the request and response are logged::
+
+  [webserver] e235780e-a5cf-415e-9326-9d33383e739e Request Details:
+  [webserver] e235780e-a5cf-415e-9326-9d33383e739e  Headers:
+  [webserver] e235780e-a5cf-415e-9326-9d33383e739e   accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
+  [webserver] e235780e-a5cf-415e-9326-9d33383e739e   accept-encoding: gzip, deflate
+  [webserver] e235780e-a5cf-415e-9326-9d33383e739e   accept-language: en-US,en;q=0.5
+  [webserver] e235780e-a5cf-415e-9326-9d33383e739e   connection: keep-alive
+  [webserver] e235780e-a5cf-415e-9326-9d33383e739e   dnt: 1
+  [webserver] e235780e-a5cf-415e-9326-9d33383e739e   host: 127.0.0.1:8081
+  [webserver] e235780e-a5cf-415e-9326-9d33383e739e   upgrade-insecure-requests: 1
+  [webserver] e235780e-a5cf-415e-9326-9d33383e739e   user-agent: Mozilla/5.0 (X11; Linux x86_64; rv:64.0) Gecko/20100101 Firefox/64.0
+  [webserver] e235780e-a5cf-415e-9326-9d33383e739e  No body
+  [webserver] e235780e-a5cf-415e-9326-9d33383e739e Response details:
+  [webserver] e235780e-a5cf-415e-9326-9d33383e739e  Headers:
+  [webserver] e235780e-a5cf-415e-9326-9d33383e739e   Connection: close
+  [webserver] e235780e-a5cf-415e-9326-9d33383e739e   Content-Length: 49
+  [webserver] e235780e-a5cf-415e-9326-9d33383e739e   Content-Type: text/html; charset=utf-8
+  [webserver] e235780e-a5cf-415e-9326-9d33383e739e   Server: PowerDNS/0.0.15896.0.gaba8bab3ab
+  [webserver] e235780e-a5cf-415e-9326-9d33383e739e  Full body: 
+  [webserver] e235780e-a5cf-415e-9326-9d33383e739e   <!html><title>Not Found</title><h1>Not Found</h1>
+  [webserver] e235780e-a5cf-415e-9326-9d33383e739e 127.0.0.1:55376 "GET /api/v1/servers/localhost/bla HTTP/1.1" 404 196
+
+The value between the hooks is a UUID that is generated for each request. This can be used to find all lines related to a single request.
+
+.. note::
+  The webserver logs these line on the NOTICE level. The :ref:`settings-loglevel` seting must be 5 or higher for these lines to end up in the log.
+
 .. _setting-webserver-password:
 
 ``webserver-password``
@@ -1638,7 +1683,7 @@ The port where webserver/API will listen on.
 -  Boolean
 -  Default: no
 
-If the webserver should print arguments. 
+If the webserver should print arguments.
 
 .. _setting-write-pid: