home | help 
KNOTC(8)			    Knot DNS				KNOTC(8)

NAME
     knotc - Knot DNS control utility

SYNOPSIS
     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    @con-
	    fig_dir@/knot.conf).

     -C, --confdb directory
	    Use  a  binary  configuration  database directory (default is @stor-
	    age_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 @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 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. Con-
	    trol 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 zone-
	    file 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 direc-
	    tory. See 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 +nozone-
	    file, +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 differ-
	    ence  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 Notes below
	    about the directory permissions.  (#)

     zone-restore [zone...] +backupdir directory [filter...]
	    Trigger a zone data and metadata restore from a specified backup di-
	    rectory.  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  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  en-
	    abled. (#)

     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  com-
	    plete  key	rollover consists of several steps and the blocking mode
	    relates to the initial one only! (#)

     zone-ksk-submitted zone... [+ttl seconds]
	    Use when the zone's KSK rollover is in submission phase. By  calling
	    this  command  the	user confirms manually that the parent zone con-
	    tains DS record for the new KSK in submission phase and the old  KSK
	    can  be  retired.  The  optional +ttl parameter specifies the parent
	    DS's TTL and possibly other delays, with the effect that the removal
	    of old KSK is postponed by this number of seconds. (#)

     zone-freeze [zone...]
	    Trigger a zone freeze. All running events will be finished	and  all
	    new  and  pending (planned) zone-changing events (load, refresh, up-
	    date, 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 freeze state
	    does not persist across server restarts! (#)

     zone-thaw [zone...]
	    Trigger dismissal of zone freeze. (#)

     zone-xfr-freeze [zone...]
	    Temporarily disable outgoing AXFR/IXFR for the zone(s). Zone  trans-
	    fer freeze state persists across server restarts. (#)

     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 transaction
	    will be committed even  if	it  contains  removals	of  non-existent
	    records 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, +jour-
	    nal, +timers, +kaspdb, and +catalog. If no filter is specified,  all
	    filters  are enabled.  If the zone is no longer configured, add +or-
	    phan parameter (zone file cannot be purged in this case). When purg-
	    ing 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 op-
	    tion. (#)

     zone-stats zone [module[.counter]]
	    Show  zone	statistics counter(s). To print also counters with value
	    0, use force option.

     zone-serial-set zone [[+]serial]
	    Set the zone SOA serial to the specified value. If the  argument  is
	    prefixed  with  +, the serial is incremented by that value (the spe-
	    cial constant MAX can be used to increment by  the	maximum  allowed
	    value  2147483647).   If  the zone transaction is open, both reading
	    and writing of the SOA serial occur within that transaction.  Other-
	    wise,  a short-lived transaction is created and committed solely for
	    setting the new SOA serial.  If no argument is specified,  the  cur-
	    rent zone SOA serial is returned.

     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 pre-
	    vents possibly existing configuration database from  purging  before
	    the import itself.	Also ensure the server is not using the configu-
	    ration 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  trans-
	    action 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
     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 process-
       ing of the command by the server. If an error is  reported,  a  more  de-
       tailed  information  about the failure can usually be found in the server
       log.

     * In the non-blocking (default) mode, knotc doesn't report  processing  er-
       rors.   The OK response to triggering commands means that the command has
       been successfully sent to the server. To verify	if  the  operation  suc-
       ceeded, 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  ac-
     count  that  knotd runs under and if the directory already exists, its per-
     missions must be appropriate for that user account.

   Interactive mode
     The utility provides interactive mode with basic line  editing  functional-
     ity, command completion, and command history.

     Interactive  mode	behavior  can  be  customized in ~/.editrc. Refer to ed-
     itrc(5) for details.

     Command history is saved in ~/.knotc_history.

EXIT VALUES
     Exit status of 0 means successful operation. Any other  exit  status  indi-
     cates 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
     knotd(8), knot.conf(5), editrc(5).

AUTHOR
     CZ.NIC, z.s.p.o. and contributors <https://www.knot-dns.cz/>

COPYRIGHT
     Copyright (C) CZ.NIC, z.s.p.o. and contributors

3.5.7				   2026-08-18				KNOTC(8)
home | help