diff options
Diffstat (limited to 'doc/man/knotc.8in')
| -rw-r--r-- | doc/man/knotc.8in | 365 |
1 files changed, 365 insertions, 0 deletions
diff --git a/doc/man/knotc.8in b/doc/man/knotc.8in new file mode 100644 index 0000000..318beb2 --- /dev/null +++ b/doc/man/knotc.8in @@ -0,0 +1,365 @@ +.\" Man page generated from reStructuredText. +. +.TH "KNOTC" "8" "@RELEASE_DATE@" "@VERSION@" "Knot DNS" +.SH NAME +knotc \- Knot DNS control utility +. +.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 +.. +.SH SYNOPSIS +.sp +\fBknotc\fP [\fIparameters\fP] \fIaction\fP [\fIaction_args\fP] +.SH DESCRIPTION +.sp +If no \fIaction\fP is specified, the program is executed in interactive mode. +.SS Parameters +.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. +.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. +.TP +\fB\-f\fP, \fB\-\-force\fP +Forced operation. Overrides some checks. +.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. +.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, +or \fBconfigure\fP for the configure summary. +.TP +\fBstop\fP +Stop the server if running. +.TP +\fBreload\fP +Reload the server configuration and modified zone files. 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\-status\fP \fIzone\fP [\fIfilter\fP] +Show the zone status. Filters are \fB+role\fP, \fB+serial\fP, \fB+transaction\fP, +\fB+events\fP, and \fB+freeze\fP\&. +.TP +\fBzone\-check\fP [\fIzone\fP\&...] +Test if the server can load the zone. Semantic checks are executed if enabled +in the configuration. When invoked with flag \fB\-f\fP/\fB\-\-force\fP an error is +returned when semantic check warning appears. (*) +.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! (#) +.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. (#) +.TP +\fBzone\-backup\fP [\fIzone\fP\&...] \fB+backupdir\fP \fIdirectory\fP [\fB+journal\fP] [\fB+nozonefile\fP] +Trigger a zone data and metadata backup to specified directory. +Optional flag \fB+journal\fP backs up also zone journal, whereas \fB+nozonefile\fP +avoids backing up current zone contents to a zone file. If zone flushing is disabled, +original zone file is backed up instead. (#) +.TP +\fBzone\-restore\fP [\fIzone\fP\&...] \fB+backupdir\fP \fIdirectory\fP [\fB+journal\fP] [\fB+nozonefile\fP] +Trigger a zone data and metadata restore from specified backup directory. +Optional flags are equivalent to \fBzone\-backup\fP\&. (#) +.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\-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. (#) +.TP +\fBzone\-thaw\fP [\fIzone\fP\&...] +Trigger dismissal of zone 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\&... [\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, +and \fB+kaspdb\fP\&. If no filter is specified, all filters are enabled. +If the zone is no longer configured, add \fB+orphan\fP filter (zone file cannot +be purged in this case). (#) +.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 +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). +Also ensure the server is not using the configuration database at the same time! (*) +.TP +\fBconf\-export\fP [\fIfilename\fP] +Export the configuration database into a config 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 Note +.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 \fI\-b\fP and \fI\-f\fP options can be placed right after the command name. +.sp +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. +.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–2021, CZ.NIC, z.s.p.o. +.\" Generated by docutils manpage writer. +. |