1KNOTC(8) Knot DNS KNOTC(8)
2
6 knotc - Knot DNS control utility
7
9 knotc [config_option] [options] [action]
10
12 This program controls a running knotd process using a socket.
13 If an action is specified, it is performed and knotc exits, otherwise
15 the program is executed in the interactive mode.
16 Config options
18 -c, --config file
19 Use a textual configuration file (default is
20 /etc/knot/knot.conf).
21 -C, --confdb directory
23 Use a binary configuration database directory (default is
24 /var/lib/knot/confdb). The default configuration database, if
25 exists, has a preference to the default configuration file.
26 Options
28 -m, --max-conf-size MiB
29 Set maximum size of the configuration database (default is 500
30 MiB, maximum 10000 MiB).
31 -s, --socket path
33 Use a control UNIX socket path (default is /run/knot/knot.sock).
34 -t, --timeout seconds
36 Use a control timeout in seconds. Set to 0 for infinity (default
37 is 60). The control socket operations are also subject to the
38 timeout parameter set on the server side in server's Control
39 configuration section.
40 -b, --blocking
42 Zone event trigger commands wait until the event is finished.
43 Control timeout is set to infinity if not forced by explicit
44 timeout specification.
45 -e, --extended
47 Show extended output (even empty items in zone status).
48 -f, --force
50 Forced operation. Overrides some checks.
51 -x, --mono
53 Don't generate colorized output.
54 -X, --color
56 Force colorized output in extended output or to a pipe.
57 -v, --verbose
59 Enable debug output.
60 -h, --help
62 Print the program help.
63 -V, --version
65 Print the program version.
66 Actions
68 status [detail]
69 Check if the server is running. Details are version for the run‐
70 ning server version, workers for the numbers of worker threads,
71 configure for the configure summary, or cert-key for the public
72 key pin of the currently used certificate.
73 stop Stop the server if running.
75 reload Reload the server configuration and modified zone files. All
77 open zone transactions will be aborted!
78 stats [module[.counter]]
80 Show global statistics counter(s). To print also counters with
81 value 0, use force option.
82 zone-check [zone...]
84 Test if the server can load the zone. Semantic checks are exe‐
85 cuted if enabled in the configuration. If invoked with the force
86 option, an error is returned when semantic check warning ap‐
87 pears. (*)
88 zone-status [zone...] [filter]
90 Show the zone status. Filters are +role, +serial, +transaction,
91 +events, +freeze, and +catalog. Empty zone parameters are omit‐
92 ted, unless the --extended option is used. A single dash in the
93 output represents an unset value. Automatic colorization can be
94 overruled using the --mono and --color options.
95 The color code is: green - zone acts as a master / red - zone
97 acts as a slave, bold font (highlited) - zone is active / normal
98 - zone is empty, underscored - zone is an interpreted catalog
99 member.
100 zone-reload [zone...]
102 Trigger a zone reload from a disk without checking its modifica‐
103 tion time. For secondary zone, the refresh event from primary
104 server(s) is scheduled; for primary zone, the notify event to
105 secondary server(s) is scheduled. An open zone transaction will
106 be aborted! If invoked with the force option, also zone modules
107 will be re-loaded, but blocking mode might not work reliably.
108 (#)
109 zone-refresh [zone...]
111 Trigger a check for the zone serial on the zone's primary
112 server. If the primary server has a newer zone, a transfer is
113 scheduled. This command is valid for secondary zones. (#)
114 zone-retransfer [zone...]
116 Trigger a zone transfer from the zone's primary server. The
117 server doesn't check the serial of the primary server's zone.
118 This command is valid for secondary zones. (#)
119 zone-notify [zone...]
121 Trigger a NOTIFY message to all configured remotes. This can
122 help in cases when previous NOTIFY had been lost or the sec‐
123 ondary servers have been offline. (#)
124 zone-flush [zone...] [+outdir directory]
126 Trigger a zone journal flush to the configured zone file. If an
127 output directory is specified, the current zone is immediately
128 dumped (in the blocking mode) to a zone file in the specified
129 directory. See Notes below about the directory permissions. (#)
130 zone-backup [zone...] +backupdir directory [filter...]
132 Trigger a zone data and metadata backup to a specified direc‐
133 tory. Available filters are +zonefile, +journal, +timers,
134 +kaspdb, +catalog, +quic, and their negative counterparts +no‐
135 zonefile, +nojournal, +notimers, +nokaspdb, +nocatalog, and +no‐
136 quic. With these filters set, zone contents, zone's journal,
137 zone-related timers, zone-related data in the KASP database to‐
138 gether with keys, zone's catalog, and the server QUIC key and
139 certificate, respectively, are backed up, or omitted from the
140 backup. By default, filters +zonefile, +timers, +kaspdb, +cata‐
141 log, +nojournal, and +noquic are set. Setting a filter for an
142 item doesn't change default settings for other items. If zone
143 flushing is disabled, the original zone file is backed up in‐
144 stead of writing out zone contents to a file. See Notes below
145 about the directory permissions. (#)
146 zone-restore [zone...] +backupdir directory [filter...]
148 Trigger a zone data and metadata restore from a specified backup
149 directory. Optional filters are equivalent to the same filters
150 of zone-backup. Restore from backups created by Knot DNS re‐
151 leases prior to 3.1 is possible with the force option. See Notes
152 below about the directory permissions. (#)
153 zone-sign [zone...]
155 Trigger a DNSSEC re-sign of the zone. Existing signatures will
156 be dropped. This command is valid for zones with DNSSEC signing
157 enabled. (#)
158 zone-keys-load [zone...]
160 Trigger a load of DNSSEC keys and other signing material from
161 KASP database (which might have been altered manually). If suit‐
162 able, re-sign the zone afterwards (keeping valid signatures in‐
163 tact). (#)
164 zone-key-rollover zone key_type
166 Trigger immediate key rollover. Publish new key and start a key
167 rollover, even when the key has a lifetime to go. Key type can
168 be ksk (also for CSK) or zsk. This command is valid for zones
169 with DNSSEC signing and automatic key management enabled. Note
170 that complete key rollover consists of several steps and the
171 blocking mode relates to the initial one only! (#)
172 zone-ksk-submitted zone...
174 Use when the zone's KSK rollover is in submission phase. By
175 calling this command the user confirms manually that the parent
176 zone contains DS record for the new KSK in submission phase and
177 the old KSK can be retired. (#)
178 zone-freeze [zone...]
180 Trigger a zone freeze. All running events will be finished and
181 all new and pending (planned) zone-changing events (load, re‐
182 fresh, update, flush, and DNSSEC signing) will be held up until
183 the zone is thawed. (#)
184 zone-thaw [zone...]
186 Trigger dismissal of zone freeze. (#)
187 zone-xfr-freeze [zone...]
189 Temporarily disable outgoing AXFR/IXFR for the zone(s). (#)
190 zone-xfr-thaw [zone...]
192 Dismiss outgoing XFR freeze. (#)
193 zone-read zone [owner [type]]
195 Get zone data that are currently being presented.
196 zone-begin zone...
198 Begin a zone transaction.
199 zone-commit zone...
201 Commit the zone transaction. All changes are applied to the
202 zone.
203 zone-abort zone...
205 Abort the zone transaction. All changes are discarded.
206 zone-diff zone
208 Get zone changes within the transaction.
209 zone-get zone [owner [type]]
211 Get zone data within the transaction.
212 zone-set zone owner [ttl] type rdata
214 Add zone record within the transaction. The first record in a
215 rrset requires a ttl value specified.
216 zone-unset zone owner [type [rdata]]
218 Remove zone data within the transaction.
219 zone-purge zone... [+orphan] [filter...]
221 Purge zone data, zone file, journal, timers, and/or KASP data of
222 specified zones. Available filters are +expire, +zonefile,
223 +journal, +timers, +kaspdb, and +catalog. If no filter is speci‐
224 fied, all filters are enabled. If the zone is no longer config‐
225 ured, add +orphan parameter (zone file cannot be purged in this
226 case). When purging orphans, always check the server log for
227 possible errors. This command always requires the force option.
228 (#)
229 zone-stats zone [module[.counter]]
231 Show zone statistics counter(s). To print also counters with
232 value 0, use force option.
233 conf-init
235 Initialize the configuration database. If the database doesn't
236 exist yet, execute this command as an intended user to ensure
237 the server is permitted to access the database (e.g. sudo -u
238 knot knotc conf-init). (*)
239 conf-check
241 Check the server configuration. (*)
242 conf-import filename
244 Import a configuration file into the configuration database. If
245 the database doesn't exist yet, execute this command as an in‐
246 tended user to ensure the server is permitted to access the
247 database (e.g. sudo -u knot knotc conf-import ...). Also ensure
248 the server is not using the configuration database at the same
249 time! (*)
250 conf-export [filename]
252 Export the configuration database into a config file or stdout.
253 (*)
254 conf-list [item]
256 List the configuration database sections or section items.
257 conf-read [item]
259 Read the item from the active configuration database.
260 conf-begin
262 Begin a writing configuration database transaction. Only one
263 transaction can be opened at a time.
264 conf-commit
266 Commit the configuration database transaction.
267 conf-abort
269 Rollback the configuration database transaction.
270 conf-diff [item]
272 Get the item difference in the transaction.
273 conf-get [item]
275 Get the item data from the transaction.
276 conf-set item [data...]
278 Set the item data in the transaction.
279 conf-unset [item] [data...]
281 Unset the item data in the transaction.
282 Notes
284 Empty or -- zone parameter means all zones or all zones with a transac‐
285 tion.
286 Use @ owner to denote the zone name.
288 Type item parameter in the form of section[[id]][.name].
290 (*) indicates a local operation which requires a configuration.
292 (#) indicates an optionally blocking operation.
294 The -b and -f options can be placed right after the command name.
296 Responses returned by knotc commands depend on the mode:
298 • In the blocking mode, knotc reports if an error occurred during pro‐
300 cessing of the command by the server. If an error is reported, a more
301 detailed information about the failure can usually be found in the
302 server log.
303 • In the non-blocking (default) mode, knotc doesn't report processing
305 errors. The OK response to triggering commands means that the com‐
306 mand has been successfully sent to the server. To verify if the oper‐
307 ation succeeded, it's necessary to check the server log.
308 Actions zone-flush, zone-backup, and zone-restore are carried out by
310 the knotd process. The directory specified must be accessible to the
311 user account that knotd runs under and if the directory already exists,
312 its permissions must be appropriate for that user account.
313 Interactive mode
315 The utility provides interactive mode with basic line editing function‐
316 ality, command completion, and command history.
317 Interactive mode behavior can be customized in ~/.editrc. Refer to ed‐
319 itrc(5) for details.
320 Command history is saved in ~/.knotc_history.
322
324 Exit status of 0 means successful operation. Any other exit status in‐
325 dicates an error.
326
328 Reload the whole server configuration
329 $ knotc reload
330 Flush the example.com and example.org zones
332 $ knotc zone-flush example.com example.org
333 Get the current server configuration
335 $ knotc conf-read server
336 Get the list of the current zones
338 $ knotc conf-read zone.domain
339 Get the primary servers for the example.com zone
341 $ knotc conf-read 'zone[example.com].master'
342 Add example.org zone with a zonefile location
344 $ knotc conf-begin
345 $ knotc conf-set 'zone[example.org]'
346 $ knotc conf-set 'zone[example.org].file' '/var/zones/example.org.zone'
347 $ knotc conf-commit
348 Get the SOA record for each configured zone
350 $ knotc zone-read -- @ SOA
351
353 knotd(8), knot.conf(5), editrc(5).
354
356 CZ.NIC Labs <https://www.knot-dns.cz>
357
359 Copyright 2010–2023, CZ.NIC, z.s.p.o.
3603.3.2 2023-10-20 KNOTC(8)