diff options
Diffstat (limited to 'doc/man/knotc.8in')
| -rw-r--r-- | doc/man/knotc.8in | 446 |
1 files changed, 0 insertions, 446 deletions
diff --git a/doc/man/knotc.8in b/doc/man/knotc.8in deleted file mode 100644 index 87242dd33..000000000 --- a/doc/man/knotc.8in +++ /dev/null @@ -1,446 +0,0 @@ -.\" Man page generated from reStructuredText. -. -. -.nr rst2man-indent-level 0 -. -.de1 rstReportMargin -\\$1 \\n[an-margin] -level \\n[rst2man-indent-level] -level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] -- -\\n[rst2man-indent0] -\\n[rst2man-indent1] -\\n[rst2man-indent2] -.. -.de1 INDENT -.\" .rstReportMargin pre: -. RS \\$1 -. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] -. nr rst2man-indent-level +1 -.\" .rstReportMargin post: -.. -.de UNINDENT -. RE -.\" indent \\n[an-margin] -.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] -.nr rst2man-indent-level -1 -.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] -.in \\n[rst2man-indent\\n[rst2man-indent-level]]u -.. -.TH "KNOTC" "8" "@RELEASE_DATE@" "@VERSION@" "Knot DNS" -.SH NAME -knotc \- Knot DNS control utility -.SH SYNOPSIS -.sp -\fBknotc\fP [\fIconfig_option\fP] [\fIoptions\fP] [\fIaction\fP] -.SH DESCRIPTION -.sp -This program controls a running \fIknotd\fP process using a socket. -.sp -If an \fIaction\fP is specified, it is performed and \fIknotc\fP exits, otherwise the program -is executed in the interactive mode. -.SS Config options -.INDENT 0.0 -.TP -\fB\-c\fP, \fB\-\-config\fP \fIfile\fP -Use a textual configuration file (default is \fB@config_dir@/knot.conf\fP). -.TP -\fB\-C\fP, \fB\-\-confdb\fP \fIdirectory\fP -Use a binary configuration database directory (default is \fB@storage_dir@/confdb\fP). -The default configuration database, if exists, has a preference to the default -configuration file. -.UNINDENT -.SS Options -.INDENT 0.0 -.TP -\fB\-m\fP, \fB\-\-max\-conf\-size\fP \fIMiB\fP -Set maximum size of the configuration database -(default is @conf_mapsize@ MiB, maximum 10000 MiB). -.TP -\fB\-s\fP, \fB\-\-socket\fP \fIpath\fP -Use a control UNIX socket path (default is \fB@run_dir@/knot.sock\fP). -.TP -\fB\-t\fP, \fB\-\-timeout\fP \fIseconds\fP -Use a control timeout in seconds. Set to 0 for infinity (default is 60). -The control socket operations are also subject to the timeout -parameter set on the server side in server\(aqs Control configuration section. -.TP -\fB\-b\fP, \fB\-\-blocking\fP -Zone event trigger commands wait until the event is finished. Control timeout -is set to infinity if not forced by explicit timeout specification. -.TP -\fB\-e\fP, \fB\-\-extended\fP -Show extended output (even empty items in zone status). -.TP -\fB\-f\fP, \fB\-\-force\fP -Forced operation. Overrides some checks. -.TP -\fB\-x\fP, \fB\-\-mono\fP -Don\(aqt generate colorized output. -.TP -\fB\-X\fP, \fB\-\-color\fP -Force colorized output in extended output or to a pipe. -.TP -\fB\-v\fP, \fB\-\-verbose\fP -Enable debug output. -.TP -\fB\-h\fP, \fB\-\-help\fP -Print the program help. -.TP -\fB\-V\fP, \fB\-\-version\fP -Print the program version. The option \fB\-VV\fP makes the program -print the compile time configuration summary. -.UNINDENT -.SS Actions -.INDENT 0.0 -.TP -\fBstatus\fP [\fIdetail\fP] -Check if the server is running. Details are \fBversion\fP for the running -server version, \fBworkers\fP for the numbers of worker threads, -\fBconfigure\fP for the configure summary, or \fBcert\-key\fP for the -public key pin of the currently used certificate. -.TP -\fBstop\fP -Stop the server if running. -.TP -\fBreload\fP -Reload the server configuration and modified zone files, and reopen the log files -if they are configured. All open zone transactions will be aborted! -.TP -\fBstats\fP [\fImodule\fP[\fB\&.\fP\fIcounter\fP]] -Show global statistics counter(s). To print also counters with value 0, use -force option. -.TP -\fBzone\-check\fP [\fIzone\fP\&...] -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. (*) -.TP -\fBzone\-status\fP [\fIzone\fP\&...] [\fIfilter\fP] -Show the zone status. Filters are \fB+role\fP, \fB+serial\fP, \fB+transaction\fP, -\fB+events\fP, \fB+freeze\fP, and \fB+catalog\fP\&. Empty zone parameters are omitted, -unless the \fB\-\-extended\fP option is used. A single dash in the output represents -an unset value. Automatic colorization can be overruled using the \fB\-\-mono\fP and -\fB\-\-color\fP options. -.sp -The color code is: -\fIgreen\fP \- zone acts as a master / \fIred\fP \- zone acts as a slave, -\fIbold font (highlited)\fP \- zone is active / \fInormal\fP \- zone is empty, -\fIunderscored\fP \- zone is an interpreted catalog member. -.TP -\fBzone\-reload\fP [\fIzone\fP\&...] -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. (#) -.TP -\fBzone\-refresh\fP [\fIzone\fP\&...] -Trigger a check for the zone serial on the zone\(aqs primary server. If -the primary server has a newer zone, a transfer is scheduled. This command is -valid for secondary zones. (#) -.TP -\fBzone\-retransfer\fP [\fIzone\fP\&...] -Trigger a zone transfer from the zone\(aqs primary server. The server -doesn\(aqt check the serial of the primary server\(aqs zone. This command is valid -for secondary zones. (#) -.TP -\fBzone\-notify\fP [\fIzone\fP\&...] -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. (#) -.TP -\fBzone\-flush\fP [\fIzone\fP\&...] [\fB+outdir\fP \fIdirectory\fP] -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 -\fI\%Notes\fP below about the directory permissions. (#) -.TP -\fBzone\-backup\fP [\fIzone\fP\&...] \fB+backupdir\fP \fIdirectory\fP [\fIfilter\fP\&...] -Trigger a zone data and metadata backup to a specified directory. -Available filters are \fB+zonefile\fP, \fB+journal\fP, \fB+timers\fP, \fB+kaspdb\fP, -\fB+keysonly\fP, \fB+catalog\fP, \fB+quic\fP, and their negative counterparts -\fB+nozonefile\fP, \fB+nojournal\fP, \fB+notimers\fP, \fB+nokaspdb\fP, \fB+nokeysonly\fP, -\fB+nocatalog\fP, and \fB+noquic\fP\&. With these filters set, zone contents, -zone\(aqs journal, zone\-related timers, zone\-related data in the KASP database -together with keys (or keys without the KASP database), zone\(aqs catalog, -and the server QUIC key and certificate, respectively, are backed up, -or omitted from the backup. By default, filters \fB+zonefile\fP, \fB+timers\fP, -\fB+kaspdb\fP, \fB+catalog\fP, \fB+quic\fP, \fB+nojournal\fP, and \fB+nokeysonly\fP -are set for backup. The same defaults are set for restore, with the only -difference being \fB+noquic\fP\&. Setting a filter for an item doesn\(aqt change the -default settings for other items. The only exception is \fB+keysonly\fP, which -disables all other filters by default, but they can still be turned on -explicitly. 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 -\fBzone\-freeze\fP\&. -See \fI\%Notes\fP below about the directory permissions. (#) -.TP -\fBzone\-restore\fP [\fIzone\fP\&...] \fB+backupdir\fP \fIdirectory\fP [\fIfilter\fP\&...] -Trigger a zone data and metadata restore from a specified backup directory. -Optional filters are equivalent to the same filters of \fBzone\-backup\fP\&. -Restore from backups created by Knot DNS releases prior to 3.1 is possible -with the force option. See \fI\%Notes\fP below about the directory -permissions. (#) -.TP -\fBzone\-sign\fP [\fIzone\fP\&...] -Trigger a DNSSEC re\-sign of the zone. Existing signatures will be dropped. -This command is valid for zones with DNSSEC signing enabled. (#) -.TP -\fBzone\-validate\fP [\fIzone\fP\&...] -Trigger a DNSSEC validation of the zone. If the validation fails and the -zone is secondary, the zone expires immediately! (#) -.TP -\fBzone\-keys\-load\fP [\fIzone\fP\&...] -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). (#) -.TP -\fBzone\-key\-rollover\fP \fIzone\fP \fIkey_type\fP -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 \fBksk\fP (also for CSK) -or \fBzsk\fP\&. 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! (#) -.TP -\fBzone\-ksk\-submitted\fP \fIzone\fP\&... -Use when the zone\(aqs 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. (#) -.TP -\fBzone\-freeze\fP [\fIzone\fP\&...] -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. Up to 8 (this limit is hardcoded) DDNS -updates per zone will be queued, subsequent updates will be refused. (#) -.TP -\fBzone\-thaw\fP [\fIzone\fP\&...] -Trigger dismissal of zone freeze. (#) -.TP -\fBzone\-xfr\-freeze\fP [\fIzone\fP\&...] -Temporarily disable outgoing AXFR/IXFR for the zone(s). (#) -.TP -\fBzone\-xfr\-thaw\fP [\fIzone\fP\&...] -Dismiss outgoing XFR freeze. (#) -.TP -\fBzone\-read\fP \fIzone\fP [\fIowner\fP [\fItype\fP]] -Get zone data that are currently being presented. -.TP -\fBzone\-begin\fP \fIzone\fP\&... -Begin a zone transaction. -.TP -\fBzone\-commit\fP \fIzone\fP\&... -Commit the zone transaction. All changes are applied to the zone. -.TP -\fBzone\-abort\fP \fIzone\fP\&... -Abort the zone transaction. All changes are discarded. -.TP -\fBzone\-diff\fP \fIzone\fP -Get zone changes within the transaction. -.TP -\fBzone\-get\fP \fIzone\fP [\fIowner\fP [\fItype\fP]] -Get zone data within the transaction. -.TP -\fBzone\-set\fP \fIzone\fP \fIowner\fP [\fIttl\fP] \fItype\fP \fIrdata\fP -Add zone record within the transaction. The first record in a rrset -requires a ttl value specified. -.TP -\fBzone\-unset\fP \fIzone\fP \fIowner\fP [\fItype\fP [\fIrdata\fP]] -Remove zone data within the transaction. -.TP -\fBzone\-purge\fP \fIzone\fP\&... [\fB+orphan\fP] [\fIfilter\fP\&...] -Purge zone data, zone file, journal, timers, and/or KASP data of specified zones. -Available filters are \fB+expire\fP, \fB+zonefile\fP, \fB+journal\fP, \fB+timers\fP, -\fB+kaspdb\fP, and \fB+catalog\fP\&. If no filter is specified, all filters are enabled. -If the zone is no longer configured, add \fB+orphan\fP parameter (zone file cannot -be purged in this case). When purging orphans, always check the server log for -possible errors. For proper operation, it\(aqs necessary to prevent ongoing changes -to the zone and triggering of zone related events during purge; use of -\fBzone\-freeze\fP is advisable. This command always requires the force option. (#) -.TP -\fBzone\-stats\fP \fIzone\fP [\fImodule\fP[\fB\&.\fP\fIcounter\fP]] -Show zone statistics counter(s). To print also counters with value 0, use -force option. -.TP -\fBconf\-init\fP -Initialize the configuration database. If the database doesn\(aqt exist yet, -execute this command as an intended user to ensure the server is permitted -to access the database (e.g. \fIsudo \-u knot knotc conf\-init\fP). (*) -.TP -\fBconf\-check\fP -Check the server configuration. (*) -.TP -\fBconf\-import\fP \fIfilename\fP [+nopurge] -Import a configuration file into the configuration database. If the database -doesn\(aqt exist yet, execute this command as an intended user to ensure the server -is permitted to access the database (e.g. \fIsudo \-u knot knotc conf\-import ...\fP). -An optional filter \fB+nopurge\fP 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! (*) -.TP -\fBconf\-export\fP [\fIfilename\fP] [+schema] -Export the configuration database (or JSON schema) into a file or stdout. (*) -.TP -\fBconf\-list\fP [\fIitem\fP] -List the configuration database sections or section items. -.TP -\fBconf\-read\fP [\fIitem\fP] -Read the item from the active configuration database. -.TP -\fBconf\-begin\fP -Begin a writing configuration database transaction. Only one transaction -can be opened at a time. -.TP -\fBconf\-commit\fP -Commit the configuration database transaction. -.TP -\fBconf\-abort\fP -Rollback the configuration database transaction. -.TP -\fBconf\-diff\fP [\fIitem\fP] -Get the item difference in the transaction. -.TP -\fBconf\-get\fP [\fIitem\fP] -Get the item data from the transaction. -.TP -\fBconf\-set\fP \fIitem\fP [\fIdata\fP\&...] -Set the item data in the transaction. -.TP -\fBconf\-unset\fP [\fIitem\fP] [\fIdata\fP\&...] -Unset the item data in the transaction. -.UNINDENT -.SS Notes -.sp -Empty or \fB\-\-\fP \fIzone\fP parameter means all zones or all zones with a transaction. -.sp -Use \fB@\fP \fIowner\fP to denote the zone name. -.sp -Type \fIitem\fP parameter in the form of \fIsection\fP[\fB[\fP\fIid\fP\fB]\fP][\fB\&.\fP\fIname\fP]. -.sp -(*) indicates a local operation which requires a configuration. -.sp -(#) indicates an optionally blocking operation. -.sp -The \fB\-b\fP and \fB\-f\fP options can be placed right after the command name. -.sp -Responses returned by \fIknotc\fP commands depend on the mode: -.INDENT 0.0 -.IP \(bu 2 -In the blocking mode, \fIknotc\fP 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. -.IP \(bu 2 -In the non\-blocking (default) mode, \fIknotc\fP doesn\(aqt report processing errors. -The \fIOK\fP response to triggering commands means that the command has been successfully -sent to the server. To verify if the operation succeeded, it\(aqs necessary to -check the server log. -.UNINDENT -.sp -Actions \fBzone\-flush\fP, \fBzone\-backup\fP, and \fBzone\-restore\fP are carried out by -the \fIknotd\fP process. The directory specified must be accessible to the user account -that \fIknotd\fP runs under and if the directory already exists, its permissions must be -appropriate for that user account. -.SS Interactive mode -.sp -The utility provides interactive mode with basic line editing functionality, -command completion, and command history. -.sp -Interactive mode behavior can be customized in \fI~/.editrc\fP\&. Refer to -\fBeditrc(5)\fP for details. -.sp -Command history is saved in \fI~/.knotc_history\fP\&. -.SH EXIT VALUES -.sp -Exit status of 0 means successful operation. Any other exit status indicates -an error. -.SH EXAMPLES -.SS Reload the whole server configuration -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -$ knotc reload -.ft P -.fi -.UNINDENT -.UNINDENT -.SS Flush the example.com and example.org zones -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -$ knotc zone\-flush example.com example.org -.ft P -.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 primary servers for the example.com zone -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -$ knotc conf\-read \(aqzone[example.com].master\(aq -.ft P -.fi -.UNINDENT -.UNINDENT -.SS Add example.org zone with a zonefile location -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -$ knotc conf\-begin -$ knotc conf\-set \(aqzone[example.org]\(aq -$ knotc conf\-set \(aqzone[example.org].file\(aq \(aq/var/zones/example.org.zone\(aq -$ knotc conf\-commit -.ft P -.fi -.UNINDENT -.UNINDENT -.SS Get the SOA record for each configured zone -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -$ knotc zone\-read \-\- @ SOA -.ft P -.fi -.UNINDENT -.UNINDENT -.SH SEE ALSO -.sp -\fBknotd(8)\fP, \fBknot.conf(5)\fP, \fBeditrc(5)\fP\&. -.SH AUTHOR -CZ.NIC Labs <https://www.knot-dns.cz> -.SH COPYRIGHT -Copyright 2010–2024, CZ.NIC, z.s.p.o. -.\" Generated by docutils manpage writer. -. |