Adding upstream version 3.3.4.upstream/3.3.4

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 438 insertions, 0 deletions

diff --git a/doc/man/knotc.8in b/doc/man/knotc.8in
new file mode 100644
index 0000000..36e7c98
--- /dev/null
+++ b/doc/man/knotc.8in
@@ -0,0 +1,438 @@
+.\" 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 \fI\%timeout\fP
+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.
+.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. 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+nokeysonly\fP, \fB+catalog\fP, \fB+quic\fP, and \fB+nojournal\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
+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 \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\-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. (#)
+.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]
+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 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.
+.