diff options
Diffstat (limited to 'doc/man_knotc.rst')
| -rw-r--r-- | doc/man_knotc.rst | 390 |
1 files changed, 390 insertions, 0 deletions
diff --git a/doc/man_knotc.rst b/doc/man_knotc.rst new file mode 100644 index 0000000..f9a5509 --- /dev/null +++ b/doc/man_knotc.rst @@ -0,0 +1,390 @@ +.. highlight:: none + +``knotc`` – Knot DNS control utility +==================================== + +Synopsis +-------- + +:program:`knotc` [*config_option*] [*options*] [*action*] + +Description +----------- + +This program controls a running `knotd` process using a socket. + +If an *action* is specified, it is performed and `knotc` exits, otherwise the program +is executed in the interactive mode. + +Config options +.............. + +**-c**, **--config** *file* + Use a textual configuration file (default is :file:`@config_dir@/knot.conf`). + +**-C**, **--confdb** *directory* + Use a binary configuration database directory (default is :file:`@storage_dir@/confdb`). + The default configuration database, if exists, has a preference to the default + configuration file. + +Options +....... + +**-m**, **--max-conf-size** *MiB* + Set maximum size of the configuration database + (default is @conf_mapsize@ MiB, maximum 10000 MiB). + +**-s**, **--socket** *path* + Use a control UNIX socket path (default is :file:`@run_dir@/knot.sock`). + +**-t**, **--timeout** *seconds* + Use a control timeout in seconds. Set to 0 for infinity (default is 60). + The control socket operations are also subject to the :ref:`timeout<control_timeout>` + parameter set on the server side in server's Control configuration section. + +**-b**, **--blocking** + Zone event trigger commands wait until the event is finished. Control timeout + is set to infinity if not forced by explicit timeout specification. + +**-e**, **--extended** + Show extended output (even empty items in zone status). + +**-f**, **--force** + Forced operation. Overrides some checks. + +**-x**, **--mono** + Don't generate colorized output. + +**-X**, **--color** + Force colorized output in extended output or to a pipe. + +**-v**, **--verbose** + Enable debug output. + +**-h**, **--help** + Print the program help. + +**-V**, **--version** + Print the program version. + +Actions +....... + +**status** [*detail*] + Check if the server is running. Details are **version** for the running + server version, **workers** for the numbers of worker threads, + **configure** for the configure summary, or **cert-key** for the + public key pin of the currently used certificate. + +**stop** + Stop the server if running. + +**reload** + Reload the server configuration and modified zone files. All open zone + transactions will be aborted! + +**stats** [*module*\ [\ **.**\ *counter*\ ]] + Show global statistics counter(s). To print also counters with value 0, use + force option. + +**zone-check** [*zone*...] + Test if the server can load the zone. Semantic checks are executed if enabled + in the configuration. If invoked with the force option, an error is returned + when semantic check warning appears. (*) + +**zone-status** [*zone*...] [*filter*] + Show the zone status. Filters are **+role**, **+serial**, **+transaction**, + **+events**, **+freeze**, and **+catalog**. Empty zone parameters are omitted, + unless the **--extended** option is used. A single dash in the output represents + an unset value. Automatic colorization can be overruled using the **--mono** and + **--color** options. + + The color code is: + *green* - zone acts as a master / *red* - zone acts as a slave, + *bold font (highlited)* - zone is active / *normal* - zone is empty, + *underscored* - zone is an interpreted catalog member. + +**zone-reload** [*zone*...] + Trigger a zone reload from a disk without checking its modification time. For + secondary zone, the refresh event from primary server(s) is scheduled; + for primary zone, the notify event to secondary server(s) is scheduled. An open + zone transaction will be aborted! If invoked with the force option, also zone + modules will be re-loaded, but blocking mode might not work reliably. (#) + +**zone-refresh** [*zone*...] + Trigger a check for the zone serial on the zone's primary server. If + the primary server has a newer zone, a transfer is scheduled. This command is + valid for secondary zones. (#) + +**zone-retransfer** [*zone*...] + Trigger a zone transfer from the zone's primary server. The server + doesn't check the serial of the primary server's zone. This command is valid + for secondary zones. (#) + +**zone-notify** [*zone*...] + Trigger a NOTIFY message to all configured remotes. This can help in cases + when previous NOTIFY had been lost or the secondary servers have been + offline. (#) + +**zone-flush** [*zone*...] [**+outdir** *directory*] + Trigger a zone journal flush to the configured zone file. If an output + directory is specified, the current zone is immediately dumped (in the + blocking mode) to a zone file in the specified directory. See + :ref:`Notes<notes>` below about the directory permissions. (#) + +**zone-backup** [*zone*...] **+backupdir** *directory* [*filter*...] + Trigger a zone data and metadata backup to a specified directory. + Available filters are **+zonefile**, **+journal**, **+timers**, **+kaspdb**, + **+keysonly**, **+catalog**, **+quic**, and their negative counterparts + **+nozonefile**, **+nojournal**, **+notimers**, **+nokaspdb**, **+nokeysonly**, + **+nocatalog**, and **+noquic**. With these filters set, zone contents, + zone's journal, zone-related timers, zone-related data in the KASP database + together with keys (or keys without the KASP database), zone's catalog, + and the server QUIC key and certificate, respectively, are backed up, + or omitted from the backup. By default, filters **+zonefile**, **+timers**, + **+kaspdb**, **+nokeysonly**, **+catalog**, **+quic**, and **+nojournal** + are set for backup. The same defaults are set for restore, with the only + difference being **+noquic**. Setting a filter for an item doesn't change + default settings for other items. If zone flushing is disabled, the original + zone file is backed up instead of writing out zone contents to a file. + When backing-up a catalog zone, it is recommended to prevent ongoing changes + to it by use of **zone-freeze**. + See :ref:`Notes<notes>` below about the directory permissions. (#) + +**zone-restore** [*zone*...] **+backupdir** *directory* [*filter*...] + Trigger a zone data and metadata restore from a specified backup directory. + Optional filters are equivalent to the same filters of **zone-backup**. + Restore from backups created by Knot DNS releases prior to 3.1 is possible + with the force option. See :ref:`Notes<notes>` below about the directory + permissions. (#) + +**zone-sign** [*zone*...] + Trigger a DNSSEC re-sign of the zone. Existing signatures will be dropped. + This command is valid for zones with DNSSEC signing enabled. (#) + +**zone-keys-load** [*zone*...] + Trigger a load of DNSSEC keys and other signing material from KASP database + (which might have been altered manually). If suitable, re-sign the zone + afterwards (keeping valid signatures intact). (#) + +**zone-key-rollover** *zone* *key_type* + Trigger immediate key rollover. Publish new key and start a key rollover, + even when the key has a lifetime to go. Key type can be **ksk** (also for CSK) + or **zsk**. This command is valid for zones with DNSSEC signing and automatic + key management enabled. Note that complete key rollover consists of several steps + and the blocking mode relates to the initial one only! (#) + +**zone-ksk-submitted** *zone*... + Use when the zone's KSK rollover is in submission phase. By calling this command + the user confirms manually that the parent zone contains DS record for the new + KSK in submission phase and the old KSK can be retired. (#) + +**zone-freeze** [*zone*...] + Trigger a zone freeze. All running events will be finished and all new and pending + (planned) zone-changing events (load, refresh, update, flush, and DNSSEC signing) + will be held up until the zone is thawed. (#) + +**zone-thaw** [*zone*...] + Trigger dismissal of zone freeze. (#) + +**zone-xfr-freeze** [*zone*...] + Temporarily disable outgoing AXFR/IXFR for the zone(s). (#) + +**zone-xfr-thaw** [*zone*...] + Dismiss outgoing XFR freeze. (#) + +**zone-read** *zone* [*owner* [*type*]] + Get zone data that are currently being presented. + +**zone-begin** *zone*... + Begin a zone transaction. + +**zone-commit** *zone*... + Commit the zone transaction. All changes are applied to the zone. + +**zone-abort** *zone*... + Abort the zone transaction. All changes are discarded. + +**zone-diff** *zone* + Get zone changes within the transaction. + +**zone-get** *zone* [*owner* [*type*]] + Get zone data within the transaction. + +**zone-set** *zone* *owner* [*ttl*] *type* *rdata* + Add zone record within the transaction. The first record in a rrset + requires a ttl value specified. + +**zone-unset** *zone* *owner* [*type* [*rdata*]] + Remove zone data within the transaction. + +**zone-purge** *zone*... [**+orphan**] [*filter*...] + Purge zone data, zone file, journal, timers, and/or KASP data of specified zones. + Available filters are **+expire**, **+zonefile**, **+journal**, **+timers**, + **+kaspdb**, and **+catalog**. If no filter is specified, all filters are enabled. + If the zone is no longer configured, add **+orphan** parameter (zone file cannot + be purged in this case). When purging orphans, always check the server log for + possible errors. For proper operation, it's necessary to prevent ongoing changes + to the zone and triggering of zone related events during purge; use of + **zone-freeze** is advisable. This command always requires the force option. (#) + +**zone-stats** *zone* [*module*\ [\ **.**\ *counter*\ ]] + Show zone statistics counter(s). To print also counters with value 0, use + force option. + +**conf-init** + Initialize the configuration database. If the database doesn't exist yet, + execute this command as an intended user to ensure the server is permitted + to access the database (e.g. *sudo -u knot knotc conf-init*). (*) + +**conf-check** + Check the server configuration. (*) + +**conf-import** *filename* [+nopurge] + Import a configuration file into the configuration database. If the database + doesn't exist yet, execute this command as an intended user to ensure the server + is permitted to access the database (e.g. *sudo -u knot knotc conf-import ...*). + An optional filter **+nopurge** prevents possibly existing configuration + database from purging before the import itself. + Also ensure the server is not using the configuration database at the same time! (*) + +**conf-export** [*filename*] + Export the configuration database into a config file or stdout. (*) + +**conf-list** [*item*] + List the configuration database sections or section items. + +**conf-read** [*item*] + Read the item from the active configuration database. + +**conf-begin** + Begin a writing configuration database transaction. Only one transaction + can be opened at a time. + +**conf-commit** + Commit the configuration database transaction. + +**conf-abort** + Rollback the configuration database transaction. + +**conf-diff** [*item*] + Get the item difference in the transaction. + +**conf-get** [*item*] + Get the item data from the transaction. + +**conf-set** *item* [*data*...] + Set the item data in the transaction. + +**conf-unset** [*item*] [*data*...] + Unset the item data in the transaction. + +.. _notes: + +Notes +..... + +Empty or **--** *zone* parameter means all zones or all zones with a transaction. + +Use **@** *owner* to denote the zone name. + +Type *item* parameter in the form of *section*\ [**[**\ *id*\ **]**\ ][**.**\ *name*]. + +(*) indicates a local operation which requires a configuration. + +(\#) indicates an optionally blocking operation. + +The **-b** and **-f** options can be placed right after the command name. + +Responses returned by `knotc` commands depend on the mode: + +- In the blocking mode, `knotc` reports if an error occurred during processing + of the command by the server. If an error is reported, a more detailed information + about the failure can usually be found in the server log. + +- In the non-blocking (default) mode, `knotc` doesn't report processing errors. + The `OK` response to triggering commands means that the command has been successfully + sent to the server. To verify if the operation succeeded, it's necessary to + check the server log. + +Actions **zone-flush**, **zone-backup**, and **zone-restore** are carried out by +the `knotd` process. The directory specified must be accessible to the user account +that `knotd` runs under and if the directory already exists, its permissions must be +appropriate for that user account. + +Interactive mode +................ + +The utility provides interactive mode with basic line editing functionality, +command completion, and command history. + +Interactive mode behavior can be customized in `~/.editrc`. Refer to +:manpage:`editrc(5)` for details. + +Command history is saved in `~/.knotc_history`. + +Exit values +----------- + +Exit status of 0 means successful operation. Any other exit status indicates +an error. + +Examples +-------- + +Reload the whole server configuration +..................................... + +:: + + $ knotc reload + +Flush the example.com and example.org zones +........................................... + +:: + + $ knotc zone-flush example.com example.org + +Get the current server configuration +.................................... + +:: + + $ knotc conf-read server + +Get the list of the current zones +................................. + +:: + + $ knotc conf-read zone.domain + +Get the primary servers for the example.com zone +................................................ + +:: + + $ knotc conf-read 'zone[example.com].master' + +Add example.org zone with a zonefile location +............................................. + +:: + + $ knotc conf-begin + $ knotc conf-set 'zone[example.org]' + $ knotc conf-set 'zone[example.org].file' '/var/zones/example.org.zone' + $ knotc conf-commit + +Get the SOA record for each configured zone +........................................... + +:: + + $ knotc zone-read -- @ SOA + +See Also +-------- + +:manpage:`knotd(8)`, :manpage:`knot.conf(5)`, :manpage:`editrc(5)`. |