Commit 48b47784 authored by Daniel Salzman's avatar Daniel Salzman

doc: use NOTE and WARNING sphinx construction

parent 910337ca
......@@ -625,21 +625,23 @@ you want to do the former. The configuration comprises only a
:ref:`mod-dnstap_sink` path parameter, which can be either a file or
a UNIX socket::
mod-dnstap:
- id: capture_all
sink: /tmp/capture.tap
mod-dnstap:
- id: capture_all
sink: /tmp/capture.tap
template:
- id: default
global-module: mod-dnstap/capture_all
template:
- id: default
global-module: mod-dnstap/capture_all
Note: to be able to use a Unix socket you need an external program to create it.
Knot DNS connects to it as a client using the libfstrm library. It operates
exactly like syslog. See `here
<https://www.nlnetlabs.nl/bugs-script/show_bug.cgi?id=741#c10>`_ for
more details.
.. NOTE::
To be able to use a Unix socket you need an external program to create it.
Knot DNS connects to it as a client using the libfstrm library. It operates
exactly like syslog. See `here
<https://www.nlnetlabs.nl/bugs-script/show_bug.cgi?id=741#c10>`_ for
more details.
Note: dnstap log files can also be created or read using ``kdig``.
.. NOTE::
Dnstap log files can also be created or read using ``kdig``.
.. _dnstap: http://dnstap.info/
......@@ -737,8 +739,9 @@ uses of this feature:
* Local zones (poor man's "views"), rest is forwarded to the public-facing server
* etc.
*Note: The module does not alter the query/response as the resolver would,
and the original transport protocol is kept as well.*
.. NOTE::
The module does not alter the query/response as the resolver would,
and the original transport protocol is kept as well.
The configuration is straightforward and just a single remote server is
required::
......@@ -794,9 +797,9 @@ And we query the nameserver with the following:
$ kdig IN AAAA ipv6.myrecord.com
... returns NOERROR, ::1
*Note: An entry in the database matches anything at the same or a lower domain
An entry in the database matches anything at the same or a lower domain
level, i.e. 'myrecord.com' matches 'a.a.myrecord.com' as well.
This can be utilized to create catch-all entries.*
This can be utilized to create catch-all entries.
You can also add authority information for the entries, provided you create
SOA + NS records for a name, like so:
......@@ -817,7 +820,7 @@ In this case, the responses will:
the example)*, but not the RR type *(this is to allow the synthesis of
negative responses)*
*Note: The SOA record applies only to the 'myrecord.com.', not to any other
The SOA record applies only to the 'myrecord.com.', not to any other
record (not even those of its subdomains). From this point of view, all records
in the database are unrelated and not hierarchical. The idea is to provide
subtree isolation for each entry.*
......@@ -846,7 +849,8 @@ Here is an example on how to use the module:
ipv6.myrecord.com. AAAA RDATA=22B ipv6_query 10.0.0.1
myrecord.com. A RDATA=10B - -
*Note: The database may be modified later on while the server is running.*
.. NOTE::
The database may be modified later on while the server is running.
* Configure the query module::
......@@ -858,8 +862,8 @@ Here is an example on how to use the module:
- id: default
global-module: mod-rosedb/default
*Note: The module accepts just one parameter – the path to the directory where
the database will be stored.*
The module accepts just one parameter – the path to the directory where
the database will be stored.
* Start the server:
......
......@@ -497,7 +497,12 @@ A template identifier.
Specifies a path of the persistent timer database. The path can be specified
as a relative path to the \fIdefault\fP template \fI\%storage\fP\&.
.sp
\fICaution:\fP This option is only available in the \fIdefault\fP template.
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This option is only available in the \fIdefault\fP template.
.UNINDENT
.UNINDENT
.sp
\fIDefault:\fP \fI\%storage\fP/timers
.SS global\-module
......@@ -505,7 +510,12 @@ as a relative path to the \fIdefault\fP template \fI\%storage\fP\&.
An ordered list of references to query modules in the form
\fImodule_name/module_id\fP\&. These modules apply to all queries.
.sp
\fICaution:\fP This option is only available in the \fIdefault\fP template.
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This option is only available in the \fIdefault\fP template.
.UNINDENT
.UNINDENT
.sp
\fIDefault:\fP not set
.SH ZONE SECTION
......@@ -675,8 +685,13 @@ flush). This is applicable when the zone is updated via IXFR, DDNS or automatic
DNSSEC signing. In order to disable automatic zonefile synchronization, \-1 value
can be used (manual zone flush is still possible).
.sp
\fICaution:\fP If you are serving large zones with frequent updates where
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
If you are serving large zones with frequent updates where
the immediate sync with a zone file is not desirable, increase the value.
.UNINDENT
.UNINDENT
.sp
\fIDefault:\fP 0 (immediate)
.SS ixfr\-from\-differences
......@@ -685,8 +700,13 @@ If enabled, the server creates zone differences from changes you made to the
zone file upon server reload. This option is relevant only if the server
is a master server for the zone.
.sp
\fICaution:\fP This option has no effect with enabled
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This option has no effect with enabled
\fI\%dnssec\-signing\fP\&.
.UNINDENT
.UNINDENT
.sp
\fIDefault:\fP off
.SS max\-journal\-size
......@@ -698,7 +718,12 @@ Maximum size of the zone journal file.
.sp
If enabled, automatic DNSSEC signing for the zone is turned on.
.sp
\fICaution:\fP Cannot be enabled on a slave zone.
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Cannot be enabled on a slave zone.
.UNINDENT
.UNINDENT
.sp
\fIDefault:\fP off
.SS kasp\-db
......@@ -727,10 +752,15 @@ Possible values:
\fBunixtime\fP – The serial is set to the current unix time
.UNINDENT
.sp
\fICaution:\fP If your serial was in other than unix time format, be careful
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
If your serial was in other than unix time format, be careful
with the transition to unix time. It may happen that the new serial will
be \(aqlower\(aq than the old one. If this is the case, the transition should be
done by hand (see RFC 1982).
.UNINDENT
.UNINDENT
.sp
\fIDefault:\fP increment
.SS module
......@@ -888,8 +918,13 @@ Possible values:
.sp
A record owner prefix.
.sp
\fICaution:\fP \fIprefix\fP doesn’t allow dots, address parts in the synthetic names are
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The value doesn’t allow dots, address parts in the synthetic names are
separated with a dash.
.UNINDENT
.UNINDENT
.sp
\fIDefault:\fP empty
.SS origin
......
......@@ -26,7 +26,9 @@ server configuration:
.. NOTE::
If dynamic updates (DDNS) are enabled for the given zone, you
might need to freeze the zone before flushing it. That can be done
similarly: ``rndc freeze example.com``
similarly::
$ rndc freeze example.com
2. Copy the fresh zone file into the zones storage directory of Knot
DNS. Its default location is ``/var/lib/knot``.
......
......@@ -52,9 +52,10 @@ Also the configuration database can be exported into a textual file::
$ knotc conf-export output.conf
*Caution:* The import and export commands access the configuration database
directly, without any interaction with the server. So it is strictly
recommended to perform these operations when the server is not running.
.. WARNING::
The import and export commands access the configuration database
directly, without any interaction with the server. So it is strictly
recommended to perform these operations when the server is not running.
.. _Dynamic configuration:
......@@ -67,7 +68,8 @@ the server must be started with a specified configuration database location
or with the default database initialized. Otherwise all the changes to the
configuration will be temporary (until the server stop).
*Note:* The database can be :ref:`imported<Configuration database>` in advance.
.. NOTE::
The database can be :ref:`imported<Configuration database>` in advance.
Most of the commands get an item name and value parameters. The item name is
in the form of ``section[identifier].name``. If the item is multivalued,
......@@ -88,7 +90,8 @@ to get all section identifiers or to get a specific configuration item::
$ knotc conf-read 'zone.domain'
$ knotc conf-read 'zone[example.com].master'
*Caution:* The following operations don't work on OpenBSD!
.. WARNING::
The following operations don't work on OpenBSD!
Modifying operations require an active configuration database transaction.
Just one transaction can be active at a time. Such a transaction then can
......@@ -107,10 +110,12 @@ section identifier or to add a value to all identified sections::
$ knotc conf-set 'zone[example.com]'
$ knotc conf-set 'zone.slave' 'slave2'
*Note:* Also the include operation can be performed. A non-absolute file
location is relative to the server binary path, not to the control binary path!::
.. NOTE::
Also the include operation can be performed. A non-absolute file
location is relative to the server binary path, not to the control binary
path!::
$ knotc conf-set 'include' '/tmp/new_zones.conf'
$ knotc conf-set 'include' '/tmp/new_zones.conf'
To unset the whole configuration or to unset the whole configuration section
or to unset an identified section or to unset an item or to unset a specific
......
......@@ -574,7 +574,8 @@ timer-db
Specifies a path of the persistent timer database. The path can be specified
as a relative path to the *default* template :ref:`storage<zone_storage>`.
*Caution:* This option is only available in the *default* template.
.. NOTE::
This option is only available in the *default* template.
*Default:* :ref:`storage<zone_storage>`/timers
......@@ -586,7 +587,8 @@ global-module
An ordered list of references to query modules in the form
*module_name/module_id*. These modules apply to all queries.
*Caution:* This option is only available in the *default* template.
.. NOTE::
This option is only available in the *default* template.
*Default:* not set
......@@ -771,8 +773,9 @@ flush). This is applicable when the zone is updated via IXFR, DDNS or automatic
DNSSEC signing. In order to disable automatic zonefile synchronization, -1 value
can be used (manual zone flush is still possible).
*Caution:* If you are serving large zones with frequent updates where
the immediate sync with a zone file is not desirable, increase the value.
.. NOTE::
If you are serving large zones with frequent updates where
the immediate sync with a zone file is not desirable, increase the value.
*Default:* 0 (immediate)
......@@ -785,8 +788,9 @@ If enabled, the server creates zone differences from changes you made to the
zone file upon server reload. This option is relevant only if the server
is a master server for the zone.
*Caution:* This option has no effect with enabled
:ref:`dnssec-signing<zone_dnssec-signing>`.
.. NOTE::
This option has no effect with enabled
:ref:`dnssec-signing<zone_dnssec-signing>`.
*Default:* off
......@@ -806,7 +810,8 @@ dnssec-signing
If enabled, automatic DNSSEC signing for the zone is turned on.
*Caution:* Cannot be enabled on a slave zone.
.. NOTE::
Cannot be enabled on a slave zone.
*Default:* off
......@@ -844,10 +849,11 @@ Possible values:
- ``increment`` – The serial is incremented according to serial number arithmetic
- ``unixtime`` – The serial is set to the current unix time
*Caution:* If your serial was in other than unix time format, be careful
with the transition to unix time. It may happen that the new serial will
be \'lower\' than the old one. If this is the case, the transition should be
done by hand (see RFC 1982).
.. NOTE::
If your serial was in other than unix time format, be careful
with the transition to unix time. It may happen that the new serial will
be \'lower\' than the old one. If this is the case, the transition should be
done by hand (see RFC 1982).
*Default:* increment
......@@ -1037,8 +1043,9 @@ prefix
A record owner prefix.
*Caution:* *prefix* doesn’t allow dots, address parts in the synthetic names are
separated with a dash.
.. NOTE::
The value doesn’t allow dots, address parts in the synthetic names are
separated with a dash.
*Default:* empty
......
......@@ -36,10 +36,11 @@ memory demanding. The rough estimate for memory requirements is
an estimate and you are advised to do your own measurements before
deploying Knot DNS to production.
Also note that to ensure uninterrupted serving of the zone, Knot DNS
employs a Read-Copy-Update mechanism instead of locking and thus
requires twice the amount of memory for the duration of incoming
transfers.
.. NOTE::
To ensure uninterrupted serving of the zone, Knot DNS
employs the Read-Copy-Update mechanism instead of locking and thus
requires twice the amount of memory for the duration of incoming
transfers.
Operating system
================
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment