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