From: Tomek Mrugalski Date: Wed, 16 Jul 2014 13:53:35 +0000 (+0200) Subject: [3427] User's Guide updated X-Git-Tag: trac3482_base~54^2~13 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=88adde43534840e25c2dc48c1522ee700a03c0c6;p=thirdparty%2Fkea.git [3427] User's Guide updated --- diff --git a/doc/guide/logging.xml b/doc/guide/logging.xml index b132c112da..c1ee94faf2 100644 --- a/doc/guide/logging.xml +++ b/doc/guide/logging.xml @@ -126,7 +126,7 @@ Right now you can only see what their names are if they are running One final note about the naming. When specifying the module name within a logger, use the name of the module - as specified in bindctl, e.g. + as specified in JSON configuration, e.g. Dhcp4 for the Dhcp4 module, Dhcp6 for the Dhcp6 module, etc. When the message is logged, the message will include the name @@ -297,65 +297,22 @@ TODO; there's a ticket to determine these levels, see #1074 output (string) - - Depending on what is set as the output destination, this - value is interpreted as follows: - + This value determines the type of output. There are several + special values allowed here: stdout (messages + are printed on standard output), stderr + (messages are printed on stderr), syslog (messages + are logged to syslog using default name, syslog:name + (messages are logged to syslog using specified name). Any other + value is interpreted as a filename that the logs should be written to. - - - - is console - - - The value of output must be one of stdout - (messages printed to standard output) or - stderr (messages printed to standard - error). - - - Note: if output is set to stderr and a lot of - messages are produced in a short time (e.g. if the logging - level is set to DEBUG), you may occasionally see some messages - jumbled up together. This is due to a combination of the way - that messages are written to the screen and the unbuffered - nature of the standard error stream. If this occurs, it is - recommended that output be set to stdout. - - - - - - is file - - - The value of output is interpreted as a file name; - log messages will be appended to this file. - - - - - - is syslog - - - The value of output is interpreted as the - syslog facility (e.g. - local0) that should be used - for log messages. - - - - - - The other options for are: +
maxsize (integer) @@ -409,7 +366,7 @@ TODO; there's a ticket to determine these levels, see #1074 Maximum number of old log files to keep around when rolling the output file. Only relevant when - is file. + is file.
@@ -419,216 +376,53 @@ TODO; there's a ticket to determine these levels, see #1074
- Example session + Example Logger configurations - In this example we want to set the global logging to - write to the file /var/log/my_bind10.log, - at severity WARN. We want the authoritative server to - log at DEBUG with debuglevel 40, to a different file - (/tmp/debug_messages). - - - - - - Start bindctl. - - - - - - ["login success "] -> config show Logging -Logging/loggers [] list - - - - - - - By default, no specific loggers are configured, in which - case the severity defaults to INFO and the output is - written to stderr. - - - - - - Let's first add a default logger: - - - - - - - > config add Logging/loggers -> config show Logging -Logging/loggers/ list (modified) - - - - - - - The loggers value line changed to indicate that it is no - longer an empty list: - - - - - - > config show Logging/loggers -Logging/loggers[0]/name "" string (default) -Logging/loggers[0]/severity "INFO" string (default) -Logging/loggers[0]/debuglevel 0 integer (default) -Logging/loggers[0]/additive false boolean (default) -Logging/loggers[0]/output_options [] list (default) - - - - - - - The name is mandatory, so we must set it. We will also - change the severity as well. Let's start with the global - logger. - - - - - - > config set Logging/loggers[0]/name * -> config set Logging/loggers[0]/severity WARN -> config show Logging/loggers -Logging/loggers[0]/name "*" string (modified) -Logging/loggers[0]/severity "WARN" string (modified) -Logging/loggers[0]/debuglevel 0 integer (default) -Logging/loggers[0]/additive false boolean (default) -Logging/loggers[0]/output_options [] list (default) + write to the console using standard output. + + + +"Logging": { + "loggers": [ + { + "name": "*", + "output_options": [ + { + "output": "stdout" + } + ], + "severity": "WARN" + } + ] +} + - - - - - Of course, we need to specify where we want the log - messages to go, so we add an entry for an output option. - - - - - - > config add Logging/loggers[0]/output_options -> config show Logging/loggers[0]/output_options -Logging/loggers[0]/output_options[0]/destination "console" string (default) -Logging/loggers[0]/output_options[0]/output "stdout" string (default) -Logging/loggers[0]/output_options[0]/flush false boolean (default) -Logging/loggers[0]/output_options[0]/maxsize 0 integer (default) -Logging/loggers[0]/output_options[0]/maxver 0 integer (default) - - - - - - - - These aren't the values we are looking for. - - - - - - > config set Logging/loggers[0]/output_options[0]/destination file -> config set Logging/loggers[0]/output_options[0]/output /var/log/kea.log -> config set Logging/loggers[0]/output_options[0]/maxsize 204800 -> config set Logging/loggers[0]/output_options[0]/maxver 8 - - - - - - - Which would make the entire configuration for this logger - look like: - - - - - - > config show all Logging/loggers -Logging/loggers[0]/name "*" string (modified) -Logging/loggers[0]/severity "WARN" string (modified) -Logging/loggers[0]/debuglevel 0 integer (default) -Logging/loggers[0]/additive false boolean (default) -Logging/loggers[0]/output_options[0]/destination "file" string (modified) -Logging/loggers[0]/output_options[0]/output "/var/log/kea.log" string (modified) -Logging/loggers[0]/output_options[0]/flush false boolean (default) -Logging/loggers[0]/output_options[0]/maxsize 204800 integer (modified) -Logging/loggers[0]/output_options[0]/maxver 8 integer (modified) - - - - - - - That looks OK, so let's commit it before we add the - configuration for the authoritative server's logger. - - - - - - > config commit - - - - - - Now that we have set it, and checked each value along - the way, adding a second entry is quite similar. - - - - - - > config add Logging/loggers -> config set Logging/loggers[1]/name Dhcp4 -> config set Logging/loggers[1]/severity DEBUG -> config set Logging/loggers[1]/debuglevel 40 -> config add Logging/loggers[1]/output_options -> config set Logging/loggers[1]/output_options[0]/destination file -> config set Logging/loggers[1]/output_options[0]/output /tmp/dhcp4_debug.log -> config commit - - - - - - - And that's it. Once we have found whatever it was we - needed the debug messages for, we can simply remove the - second logger to let the DHCP server use the - same settings as the rest. - - - - - - > config remove Logging/loggers[1] -> config commit - - - - - - - And every module will now be using the values from the - logger named *. - - - +In this second example, we want to store debug log messages +in a file that is at most 2MB and keep up to 8 copies of old logfiles. +Once the logfile grows to 2MB, it will be renamed and a new file +file be created. + + +"Logging": { + "loggers": [ + { + "name": "kea", + "output_options": [ + { + "output": "/var/log/kea-debug.log", + "maxver": 8, + "maxsize": 204800, + "destination": "file" + } + ], + "severity": "DEBUG", + "debuglevel": 99 + } + ] +}