Commit fa75e560 authored by Daniel Salzman's avatar Daniel Salzman

doc: add dynamic configuration

parent 845a15e0
......@@ -73,6 +73,8 @@ Print help and usage.
.sp
If the optional \fIzone\fP argument is not specified, the command is applied to all
zones.
Configuration \fIitem\fP is in the \fIsection\fP[\fB[\fP\fIid\fP\fB]\fP][\fB\&.\fP\fIitem\fP]
format.
.INDENT 0.0
.TP
\fBstop\fP
......@@ -105,12 +107,57 @@ Estimate memory consumption for zones.
\fBsignzone\fP \fIzone\fP\&...
Re\-sign the zone (drop all existing signatures and create new ones).
.TP
\fBimport\fP \fIfile\fP
Import a configuration database from file. This is a potentially dangerous
operation, thus the \fB\-f\fP flag is required.
\fBconf\-import\fP \fIfilename\fP
Offline import of the configuration DB from a file. This is a
potentially dangerous operation so the \fB\-f\fP flag is required. Also the
destination configuration DB must be specified via \fB\-C\fP\&. Ensure the server
is not running!
.TP
\fBexport\fP \fIfile\fP
Export the configuration database to a file.
\fBconf\-export\fP \fIfilename\fP
Export the configuration DB to a file. If no source configuration DB is
specified, the temporary DB, corresponding to textual configuration file, is
used.
.TP
\fBconf\-desc\fP [\fIsection\fP]
Get the configuration section items list. If no section is specified,
the list of sections is returned.
.TP
\fBconf\-read\fP [\fIitem\fP]
Read from the current configuration DB.
.TP
\fBconf\-write\fP \fIitem\fP [\fIdata\fP\&...]
Write to the current configuration DB. A writing transaction is started
and finished automatically.
.TP
\fBconf\-delete\fP [\fIitem\fP] [\fIdata\fP\&...]
Delete from the current configuration DB. A writing transaction is started
and finished automatically.
.TP
\fBconf\-begin\fP
Begin a writing configuration DB transaction. Only one transaction can be
opened at a time.
.TP
\fBconf\-commit\fP
Commit the current writing configuration DB transaction.
.TP
\fBconf\-abort\fP
Abort the current writing configuration DB transaction.
.TP
\fBconf\-diff\fP [\fIitem\fP]
Get the difference between the active writing transaction and the current
configuration DB. Requires active writing configuration DB transaction.
.TP
\fBconf\-get\fP [\fIitem\fP]
Read from the active writing configuration DB transaction.
Requires active writing configuration DB transaction.
.TP
\fBconf\-set\fP \fIitem\fP [\fIdata\fP\&...]
Write to the active writing configuration DB transaction.
Requires active writing configuration DB transaction.
.TP
\fBconf\-unset\fP [\fIitem\fP] [\fIdata\fP\&...]
Delete from the active writing configuration DB transaction.
Requires active writing configuration DB transaction.
.UNINDENT
.SH EXAMPLES
.SS Setup a key file for remote control
......@@ -164,6 +211,53 @@ $ knotc \-c knot.conf flush
.fi
.UNINDENT
.UNINDENT
.SS Get the current server configuration
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ knotc conf\-read server
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Get the list of the current zones
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ knotc conf\-read zone.domain
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Get the master remotes for the example.com zone
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ knotc conf\-read zone[example.com].master
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Add example.eu zone with a zonefile location
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ knotc conf\-begin
$ knotc conf\-set zone[example.eu]
$ knotc conf\-set zone[example.eu].file "/var/zones/example.eu.zone"
$ knotc conf\-commit
.ft P
.fi
.UNINDENT
.UNINDENT
.SH SEE ALSO
.sp
\fIknotd(8)\fP, \fIknot.conf(5)\fP\&.
......
......@@ -51,6 +51,8 @@ Actions
If the optional *zone* argument is not specified, the command is applied to all
zones.
Configuration *item* is in the *section*\ [**[**\ *id*\ **]**\ ][**.**\ *item*]
format.
**stop**
Stop server (no-op if not running).
......@@ -82,12 +84,57 @@ zones.
**signzone** *zone*...
Re-sign the zone (drop all existing signatures and create new ones).
**import** *file*
Import a configuration database from file. This is a potentially dangerous
operation, thus the **-f** flag is required.
**conf-import** *filename*
Offline import of the configuration DB from a file. This is a
potentially dangerous operation so the **-f** flag is required. Also the
destination configuration DB must be specified via **-C**. Ensure the server
is not running!
**export** *file*
Export the configuration database to a file.
**conf-export** *filename*
Export the configuration DB to a file. If no source configuration DB is
specified, the temporary DB, corresponding to textual configuration file, is
used.
**conf-desc** [*section*]
Get the configuration section items list. If no section is specified,
the list of sections is returned.
**conf-read** [*item*]
Read from the current configuration DB.
**conf-write** *item* [*data*...]
Write to the current configuration DB. A writing transaction is started
and finished automatically.
**conf-delete** [*item*] [*data*...]
Delete from the current configuration DB. A writing transaction is started
and finished automatically.
**conf-begin**
Begin a writing configuration DB transaction. Only one transaction can be
opened at a time.
**conf-commit**
Commit the current writing configuration DB transaction.
**conf-abort**
Abort the current writing configuration DB transaction.
**conf-diff** [*item*]
Get the difference between the active writing transaction and the current
configuration DB. Requires active writing configuration DB transaction.
**conf-get** [*item*]
Read from the active writing configuration DB transaction.
Requires active writing configuration DB transaction.
**conf-set** *item* [*data*...]
Write to the active writing configuration DB transaction.
Requires active writing configuration DB transaction.
**conf-unset** [*item*] [*data*...]
Delete from the active writing configuration DB transaction.
Requires active writing configuration DB transaction.
Examples
--------
......@@ -123,6 +170,37 @@ Flush all zones locally
$ knotc -c knot.conf flush
Get the current server configuration
....................................
::
$ knotc conf-read server
Get the list of the current zones
.................................
::
$ knotc conf-read zone.domain
Get the master remotes for the example.com zone
...............................................
::
$ knotc conf-read zone[example.com].master
Add example.eu zone with a zonefile location
............................................
::
$ knotc conf-begin
$ knotc conf-set zone[example.eu]
$ knotc conf-set zone[example.eu].file "/var/zones/example.eu.zone"
$ knotc conf-commit
See Also
--------
......
......@@ -40,13 +40,110 @@ Configuration database
In the case of a huge configuration file, the configuration can be preloaded
into the server's configuration database::
$ knotc import input.conf
$ knotc -C db_path conf-import input.conf
Also the configuration database can be exported into a configuration file::
$ knotc export output.conf
$ knotc -C db_path conf-export output.conf
It is recommended to perform these actions without server running.
*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.
.. _Dynamic configuration:
Dynamic configuration
=====================
The configuration database can be accessed using the server remote control
during the running server. To get the full power of the dynamic configuration,
the server must be started with a specified configuration database location::
$ knotd -C /var/lib/knot/confdb
*Note:* The database can be :ref:`imported<Configuration database>` in advance.
Otherwise all the changes to the configuration are temporary (until the server
stop).
Most of the commands get item name and value parameters. An item is in the form
of ``section[identifier].item``. If the item is multivalued, more values
can be specified with a space separation.
To get the list of configuration sections or to get the list of section items::
$ knotc conf-desc
$ knotc conf-desc server
To get the whole configuration or to get the whole configuration section or
to get all section identifiers or to get a specific configuration item::
$ knotc conf-read
$ knotc conf-read remote
$ knotc conf-read zone.domain
$ knotc conf-read zone[example.com].master
*Caution:* 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
be aborted or commited. A semantic check is executed automatically before
every commit::
$ knotc conf-begin
$ knotc conf-abort
$ knotc conf-commit
To set a configuration item value or to add more values or to add a new
section identifier or to add a value to all identified sections::
$ knotc conf-set server.identity "Knot DNS"
$ knotc conf-set server.listen 0.0.0.0@53 ::@53
$ knotc conf-set zone[example.com]
$ knotc conf-set zone.slave slave2
*Note:* Also the include operation can be performed (the file location is
relative to the server binary!)::
$ 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
item value::
$ knotc conf-unset
$ knotc conf-unset zone
$ knotc conf-unset zone[example.com]
$ knotc conf-unset zone[example.com].master
$ knotc conf-unset zone[example.com].master remote2 remote5
To get the change between the current configuration and the active transaction
for the whole configuration or for a specific section or for a specific
identified section or for a specific item::
$ knotc conf-diff
$ knotc conf-diff zone
$ knotc conf-diff zone[example.com]
$ knotc conf-diff zone[example.com].master
For simple and infrequent modifications, there are "lazy" variants of
``conf-set`` and ``conf-unset`` operations (``conf-write`` and ``conf-delete``
respectively) which activate and commit/abort the change automatically.
An example of possible configuration initialization::
$ knotc conf-write server.listen 0.0.0.0@53 ::@53
$ knotc conf-begin
$ knotc conf-set remote[master_server]
$ knotc conf-set remote[master_server].address 192.168.1.1
$ knotc conf-set template[default]
$ knotc conf-set template[default].storage /var/lib/knot/zones/
$ knotc conf-set template[default].master master_server
$ knotc conf-diff
$ knotc conf-commit
$ knotc conf-write zone[example.com]
.. _Running a slave server:
......
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