diff --git a/doc/man/knotc.8in b/doc/man/knotc.8in index c2980e38d8d37fc517c4cc33bd6873b718b99547..a340b07ccdec9b87c0197cc5ff4e39879929b168 100644 --- a/doc/man/knotc.8in +++ b/doc/man/knotc.8in @@ -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\&. diff --git a/doc/man_knotc.rst b/doc/man_knotc.rst index 27b66c0e2c35969d8a7574085b07047121bd2bd6..cf059457f9936f815ebe19e41ec80755974cf5ab 100644 --- a/doc/man_knotc.rst +++ b/doc/man_knotc.rst @@ -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 -------- diff --git a/doc/operation.rst b/doc/operation.rst index 02e5f650629e3f5209a2f2b1103cbfe2267f019e..d0f5669a414c7ae6262b0ac08954b01904c58231 100644 --- a/doc/operation.rst +++ b/doc/operation.rst @@ -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: