From 205e02097b5a0710288bbb27e69cf15fa949e830 Mon Sep 17 00:00:00 2001
From: Jan Kadlec <jan.kadlec@nic.cz>
Date: Thu, 16 Aug 2012 13:57:56 +0200
Subject: [PATCH] Fixed references in documentation. Added text.
- Logging section completed
- Added examples for remotes and zones
- typo fixes
- needs review
---
doc/configuration.texi | 2 +-
doc/knot.texi | 2 +-
doc/reference.texi | 164 ++++++++++++++++++++++++++++++++++++++---
doc/running.texi | 10 +--
4 files changed, 159 insertions(+), 19 deletions(-)
diff --git a/doc/configuration.texi b/doc/configuration.texi
index ac5a0050ef..7c28ef66b7 100644
--- a/doc/configuration.texi
+++ b/doc/configuration.texi
@@ -77,7 +77,7 @@ The @code{@ref{zones}} statement is the one probably most important,
because it defines the zones Knot DNS will serve. In its most simple
form you define zone by it's name and defined the filename where Knot
DNS can find the zone contents. You can turn on more detailed semantic
-checks of zone file in this statement. Refer to @code{@ref{zones Semantic checks}} to see
+checks of zone file in this statement. Refer to @code{@ref{zones List of zone semantic checks}} to see
which checks are enabled by default and which are optional. If Knot is
being run as a master server, experimental feature @code{ixfr-from-differences}
can be enabled to create IXFR changesets from changest made to master zone file.
diff --git a/doc/knot.texi b/doc/knot.texi
index 74ca87a8f0..95482134c9 100644
--- a/doc/knot.texi
+++ b/doc/knot.texi
@@ -198,8 +198,8 @@ Statement Definition and Usage
@code{zones} Statement
* zones Syntax::
-* zones Semantic checks::
* zones Statement Definition and Grammar::
+* zones List of zone semantic checks::
@code{log} Statement
diff --git a/doc/reference.texi b/doc/reference.texi
index df894f8500..e34fd9a689 100644
--- a/doc/reference.texi
+++ b/doc/reference.texi
@@ -338,6 +338,7 @@ server for different zone.
@menu
* remotes Syntax::
* remotes Statement Definition and Grammar::
+* remotes Examples::
@end menu
@node remotes Syntax
@@ -384,19 +385,45 @@ server for different zone.
@subsubsection port
@vindex port
-@code{port} section contains a port number for current @code{remote}.
+@code{port} section contains a port number for current @code{remote}. This section is optional with default port set to 53.
@node key
@subsubsection key
@vindex key
-@code{key} section contains a key associated with this @code{remote}.
+@code{key} section contains a key associated with this @code{remote}. This section is optional.
+
@node via
@subsubsection via
@vindex via
-@code{via} section specifies which interface will be used to comunnicate with this @code{remote}.
+@code{via} section specifies which interface will be used to comunnicate with this @code{remote}. This section is optional.
+
+@node remotes Examples
+@subsection remotes Examples
+
+@example
+
+remotes @{
+
+ # Format 1:
+ server0 @{
+ address 127.0.0.1;
+ port 53531;
+ key key0.server0;
+ via ipv4;
+ via 82.35.64.59; # IPv4
+ via [::cafe]; # IPv6
+ @}
+
+ # Format 2:
+ server1 @{
+ address 127.0.0.1@@53001;
+ @}
+@}
+
+@end example
@node zones
@section @code{zones} Statement
@@ -405,8 +432,9 @@ The @code{zones} statement contains definition of zones served by Knot DNS.
@menu
* zones Syntax::
-* zones Semantic checks::
-* zones Statement Definition and Grammar::
+* zones Statement Definition and Grammar::
+* zones Example::
+* zones List of zone semantic checks::
@end menu
@node zones Syntax
@@ -460,7 +488,7 @@ The @code{zones} statement contains definition of zones served by Knot DNS.
@vindex zone_id
@code{zone_id} is zone origin, and as such is a domain name that may or may not end with a ".".
-If no $ORIGIN directive is inside actual zone file, this domain name will be used in place of "@".
+If no $ORIGIN directive is inside actual zone file, this domain name will be used in place of "@@".
@node file
@subsubsection file
@@ -500,7 +528,7 @@ Remotes are defined in @ref{remotes}.
@vindex semantic-checks
@code{semantic-checks} statement turns on optional semantic checks for this particular zone.
-See @ref{zones Semantic checks} for more information. Possible values are @code{on} and @code{off}.
+See @ref{zones List of zone semantic checks} for more information. Possible values are @code{on} and @code{off}.
Disabled by default.
@node ixfr-from-differences
@@ -545,7 +573,40 @@ to its file on a disk (as set in @ref{file}). Possible values are 1 to INT_MAX,
@code{ixfr-fslimit} sets a maximum size for zone's journal. Possible values are 1 to INT_MAX, with optional suffixes k, m and G. I.e. 1k, 1m and 1G with default value not being set, meaning that journal file can grow without limitations.
-@node zones Semantic checks
+@node zones Example
+@subsection zones Example
+
+@example
+@group
+zones @{
+
+ # Shared options for all listed zones
+ ixfr-from-differences off;
+ semantic-checks off;
+ disable-any off;
+ notify-timeout 60;
+ notify-retries 5;
+ zonefile-sync 1h;
+ ixfr-fslimit 1G;
+ example.com @{
+ file "samples/example.com.zone";
+ ixfr-from-differences off; #experimental
+ disable-any off;
+ semantic-checks on;
+ notify-timeout 60;
+ notify-retries 5;
+ zonefile-sync 1h;
+ xfr-in server0;
+ xfr-out server0, server1;
+ notify-in server0;
+ notify-out server0, server1;
+ @}
+@}
+
+@end group
+@end example
+
+@node zones List of zone semantic checks
@subsection List of zone semantic checks
The @code{semantic-checks} statement turns on extra zone file semantic
@@ -593,7 +654,8 @@ loaded even upon discovering an error:
@menu
* log Syntax::
-* log Statement Definition and Grammar::
+* log Statement Definition and Grammar::
+* log Example::
@end menu
@node log Syntax
@@ -603,7 +665,9 @@ loaded even upon discovering an error:
@code{log} @code{@{}
@kbd{log_name} @code{@{}
[ @kbd{category} @kbd{severity} [ @kbd{severity} @dots{} ]@code{;} ]
- [ @code{file} @kbd{filename} @kbd{severity} [ @kbd{severity} @dots{} ]@code{;} ]
+ [ @code{log_file} @kbd{filename} @{
+ [ @kbd{category} @kbd{severity} [ @kbd{severity} @dots{} ]@code{;} ]
+ @} ]
@code{@}}
@code{@}}
@@ -612,9 +676,85 @@ loaded even upon discovering an error:
@node log Statement Definition and Grammar
@subsection Statement Definition and Grammar
+@menu
+* log_name::
+* category::
+* severity::
+* log_file::
+@end menu
+
The @code{log} statement configures logging output of Knot DNS. You
-can configure Knot DNS to log into file or system log. Each log
-message has it's priority and you can configure priorities for each
+can configure Knot DNS to log into file or system log. There are several
+logging categories to choose from. Each log
+message has its priority and you can configure priorities for each
log destination.
+@node log_name
+@subsubsection @kbd{log_name}
+@vindex @kbd{log_name}
+
+@kbd{log_name} recognizes 3 symbolic log names :
+@itemize
+@item @emph{stdout} - logging to standard output
+@item @emph{stderr} - logging to standard error output
+@item @emph{syslog} - logging to syslog
+@end itemize
+
+@node category
+@subsubsection @kbd{category}
+@vindex category
+
+Knot DNS allows user to choose from these logging categories:
+
+@itemize
+@item @emph{server} - Messages related to general operation of the server.
+@item @emph{zone} - Messages related to zones, zone parsing and loading.
+@item @emph{answering} - Messages regarding query processing and response creation.
+@item @emph{any} - All categories.
+@end itemize
+
+@node severity
+@subsubsection @kbd{severity}
+@vindex severity
+
+Knot DNS has the following logging severities:
+@itemize
+@item @emph{debug} - Debug messages, must be turned on at compile time (@pxref{Enabling debug messages in server}).
+@item @emph{info} - Informational message.
+@item @emph{notice} - Server notices and hints.
+@item @emph{warning} - Warnings that might require user action.
+@item @emph{error} - Recoverable error. Action should be taken.
+@item @emph{all} - All severities.
+@end itemize
+
+@node log_file
+@subsubsection @kbd{log_file}
+@vindex @kbd{log_file}
+
+@kbd{log_file} is either absolute or relative path to file user wants to log to.
+See following example for clarification.
+
+@node log Example
+@subsection log Example
+
+@example
+
+log @{
+
+ syslog @{
+ any error;
+ zone warning, notice;
+ server info;
+ @}
+
+ stderr @{
+ any error, warning;
+ @}
+
+ file "/tmp/knot-sample/knotd.debug" @{
+ server debug;
+ @}
+@}
+
+@end example
diff --git a/doc/running.texi b/doc/running.texi
index a636b942c1..fb5c69bb83 100644
--- a/doc/running.texi
+++ b/doc/running.texi
@@ -1,4 +1,4 @@
-@node Running Knot DNS, Security Considerations, Knot DNS Configuration, Top
+@node Running Knot DNS, Troubleshooting, Knot DNS Configuration, Top
@chapter Running Knot DNS
@menu
@@ -160,12 +160,12 @@ Or use the @code{-a} again.
$ knotc -a -c master.conf reload # compile zones and reconfigure
@end example
-If you want IXFR-out changesets created from changes you make to a zone file, enable @code{ixfr-from-differences}
+If you want @emph{IXFR-out} changesets created from changes you make to a zone file, enable @code{ixfr-from-differences}
in @ref{zones} statement, then compile the zone and reload your server as seen above.
-If SOA's serial is not changed no changesets will be created. Please note
-that this feature is in experimental stage and should be used with care.
+If @emph{SOA}'s @emph{serial} is not changed no changesets will be created. Please note
+that this feature is in @emph{experimental} stage and should be used with care.
If you encounter a bug using this feature, please send it to Knot developers
-as explained in TODO REF reporting.
+as explained in @ref{Submitting a bugreport} reporting.
You can also choose to tear-down the server fully and restart with the @code{knotc restart} action.
@example
--
GitLab