402 lines
14 KiB
ReStructuredText
402 lines
14 KiB
ReStructuredText
.. 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. The option **-VV** makes the program
|
||
print the compile time configuration summary.
|
||
|
||
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, and reopen the log files
|
||
if they are configured. 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 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
|
||
: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**, **+catalog**, **+quic**, **+nojournal**, and **+nokeysonly**
|
||
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 the
|
||
default settings for other items. The only exception is **+keysonly**, 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
|
||
**zone-freeze**. The force option allows an already existing backupdir to
|
||
be overwritten. 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-validate** [*zone*...]
|
||
Trigger a DNSSEC validation of the zone. If the validation fails and the
|
||
zone is secondary, the zone expires immediately! (#)
|
||
|
||
**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. Up to 8 (this limit is hardcoded) DDNS
|
||
updates per zone will be queued, subsequent updates will be refused. (#)
|
||
|
||
**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*... [**+benevolent**]
|
||
Begin a zone transaction. If **+benevolent** is used, the zone transaction will
|
||
be committed even when it contains removals of non-existing or additions of
|
||
existing records.
|
||
|
||
**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*] [+schema]
|
||
Export the configuration database (or JSON schema) into a 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)`.
|