450 lines
16 KiB
Groff
450 lines
16 KiB
Groff
.\" 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" "2025-04-10" "3.4.6" "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/usr/local/etc/knot/knot.conf\fP).
|
||
.TP
|
||
\fB\-C\fP, \fB\-\-confdb\fP \fIdirectory\fP
|
||
Use a binary configuration database directory (default is \fB/usr/local/var/lib/knot/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 500 MiB, maximum 10000 MiB).
|
||
.TP
|
||
\fB\-s\fP, \fB\-\-socket\fP \fIpath\fP
|
||
Use a control UNIX socket path (default is \fB/usr/local/var/run/knot/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. 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 zonefile
|
||
synchronization is disabled, the force option must be used.
|
||
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\&. The force option allows an already existing backupdir to
|
||
be overwritten. 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\&... [\fB+benevolent\fP]
|
||
Begin a zone transaction. If \fB+benevolent\fP is used, the zone transaction will
|
||
be committed even when it contains removals of non\-existing or additions of
|
||
existing records.
|
||
.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–2025, CZ.NIC, z.s.p.o.
|
||
.\" Generated by docutils manpage writer.
|
||
.
|