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 -f, --force
46 Forced operation. Overrides some checks.
47 -v, --verbose
49 Enable debug output.
50 -h, --help
52 Print the program help.
53 -V, --version
55 Print the program version.
56 Actions
58 status [detail]
59 Check if the server is running. Details are version for the run‐
60 ning server version, workers for the numbers of worker threads,
61 or configure for the configure summary.
62 stop Stop the server if running.
64 reload Reload the server configuration and modified zone files. All
66 open zone transactions will be aborted!
67 stats [module[.counter]]
69 Show global statistics counter(s). To print also counters with
70 value 0, use force option.
71 zone-check [zone...]
73 Test if the server can load the zone. Semantic checks are exe‐
74 cuted if enabled in the configuration. If invoked with the force
75 option, an error is returned when semantic check warning ap‐
76 pears. (*)
77 zone-status [zone...] [filter]
79 Show the zone status. Filters are +role, +serial, +transaction,
80 +events, +freeze, and +catalog.
81 zone-reload [zone...]
83 Trigger a zone reload from a disk without checking its modifica‐
84 tion time. For secondary zone, the refresh event from primary
85 server(s) is scheduled; for primary zone, the notify event to
86 secondary server(s) is scheduled. An open zone transaction will
87 be aborted! If invoked with the force option, also zone modules
88 will be re-loaded, but blocking mode might not work reliably.
89 (#)
90 zone-refresh [zone...]
92 Trigger a check for the zone serial on the zone's primary
93 server. If the primary server has a newer zone, a transfer is
94 scheduled. This command is valid for secondary zones. (#)
95 zone-retransfer [zone...]
97 Trigger a zone transfer from the zone's primary server. The
98 server doesn't check the serial of the primary server's zone.
99 This command is valid for secondary zones. (#)
100 zone-notify [zone...]
102 Trigger a NOTIFY message to all configured remotes. This can
103 help in cases when previous NOTIFY had been lost or the sec‐
104 ondary servers have been offline. (#)
105 zone-flush [zone...] [+outdir directory]
107 Trigger a zone journal flush to the configured zone file. If an
108 output directory is specified, the current zone is immediately
109 dumped (in the blocking mode) to a zone file in the specified
110 directory. See Notes below about the directory permissions. (#)
111 zone-backup [zone...] +backupdir directory [filter...]
113 Trigger a zone data and metadata backup to a specified direc‐
114 tory. Available filters are +zonefile, +journal, +timers,
115 +kaspdb, +catalog, and their negative counterparts +nozonefile,
116 +nojournal, +notimers, +nokaspdb, and +nocatalog. With these
117 filters set, zone contents, zone's journal, zone related timers,
118 zone related data in the KASP database together with keys, and
119 zone's catalog, respectively, are backed up, or omitted from the
120 backup. By default, filters +zonefile, +timers, +kaspdb, +cata‐
121 log, and +nojournal are set. Setting a filter for an item
122 doesn't change default settings for other items. If zone flush‐
123 ing is disabled, original zone file is backed up instead of
124 writing out zone contents to a file. See Notes below about the
125 directory permissions. (#)
126 zone-restore [zone...] +backupdir directory [filter...]
128 Trigger a zone data and metadata restore from a specified backup
129 directory. Optional filters are equivalent to the same filters
130 of zone-backup. Restore from backups created by Knot DNS re‐
131 leases prior to 3.1 is possible with the force option. See Notes
132 below about the directory permissions. (#)
133 zone-sign [zone...]
135 Trigger a DNSSEC re-sign of the zone. Existing signatures will
136 be dropped. This command is valid for zones with DNSSEC signing
137 enabled. (#)
138 zone-keys-load [zone...]
140 Trigger a load of DNSSEC keys and other signing material from
141 KASP database (which might have been altered manually). If suit‐
142 able, re-sign the zone afterwards (keeping valid signatures in‐
143 tact). (#)
144 zone-key-rollover zone key_type
146 Trigger immediate key rollover. Publish new key and start a key
147 rollover, even when the key has a lifetime to go. Key type can
148 be ksk (also for CSK) or zsk. This command is valid for zones
149 with DNSSEC signing and automatic key management enabled. Note
150 that complete key rollover consists of several steps and the
151 blocking mode relates to the initial one only! (#)
152 zone-ksk-submitted zone...
154 Use when the zone's KSK rollover is in submission phase. By
155 calling this command the user confirms manually that the parent
156 zone contains DS record for the new KSK in submission phase and
157 the old KSK can be retired. (#)
158 zone-freeze [zone...]
160 Trigger a zone freeze. All running events will be finished and
161 all new and pending (planned) zone-changing events (load, re‐
162 fresh, update, flush, and DNSSEC signing) will be held up until
163 the zone is thawed. (#)
164 zone-thaw [zone...]
166 Trigger dismissal of zone freeze. (#)
167 zone-xfr-freeze [zone...]
169 Temporarily disable outgoing AXFR/IXFR for the zone(s). (#)
170 zone-xfr-thaw [zone...]
172 Dismiss outgoing XFR freeze. (#)
173 zone-read zone [owner [type]]
175 Get zone data that are currently being presented.
176 zone-begin zone...
178 Begin a zone transaction.
179 zone-commit zone...
181 Commit the zone transaction. All changes are applied to the
182 zone.
183 zone-abort zone...
185 Abort the zone transaction. All changes are discarded.
186 zone-diff zone
188 Get zone changes within the transaction.
189 zone-get zone [owner [type]]
191 Get zone data within the transaction.
192 zone-set zone owner [ttl] type rdata
194 Add zone record within the transaction. The first record in a
195 rrset requires a ttl value specified.
196 zone-unset zone owner [type [rdata]]
198 Remove zone data within the transaction.
199 zone-purge zone... [filter...]
201 Purge zone data, zone file, journal, timers, and/or KASP data of
202 specified zones. Available filters are +expire, +zonefile,
203 +journal, +timers, and +kaspdb. If no filter is specified, all
204 filters are enabled. If the zone is no longer configured, add
205 +orphan filter (zone file cannot be purged in this case). This
206 command always requires the force option. (#)
207 zone-stats zone [module[.counter]]
209 Show zone statistics counter(s). To print also counters with
210 value 0, use force option.
211 conf-init
213 Initialize the configuration database. If the database doesn't
214 exist yet, execute this command as an intended user to ensure
215 the server is permitted to access the database (e.g. sudo -u
216 knot knotc conf-init). (*)
217 conf-check
219 Check the server configuration. (*)
220 conf-import filename
222 Import a configuration file into the configuration database. If
223 the database doesn't exist yet, execute this command as an in‐
224 tended user to ensure the server is permitted to access the
225 database (e.g. sudo -u knot knotc conf-import ...). Also ensure
226 the server is not using the configuration database at the same
227 time! (*)
228 conf-export [filename]
230 Export the configuration database into a config file or stdout.
231 (*)
232 conf-list [item]
234 List the configuration database sections or section items.
235 conf-read [item]
237 Read the item from the active configuration database.
238 conf-begin
240 Begin a writing configuration database transaction. Only one
241 transaction can be opened at a time.
242 conf-commit
244 Commit the configuration database transaction.
245 conf-abort
247 Rollback the configuration database transaction.
248 conf-diff [item]
250 Get the item difference in the transaction.
251 conf-get [item]
253 Get the item data from the transaction.
254 conf-set item [data...]
256 Set the item data in the transaction.
257 conf-unset [item] [data...]
259 Unset the item data in the transaction.
260 Notes
262 Empty or -- zone parameter means all zones or all zones with a transac‐
263 tion.
264 Use @ owner to denote the zone name.
266 Type item parameter in the form of section[[id]][.name].
268 (*) indicates a local operation which requires a configuration.
270 (#) indicates an optionally blocking operation.
272 The -b and -f options can be placed right after the command name.
274 Responses returned by knotc commands depend on the mode:
276 • In the blocking mode, knotc reports if an error occurred during pro‐
278 cessing of the command by the server. If an error is reported, a more
279 detailed information about the failure can usually be found in the
280 server log.
281 • In the non-blocking (default) mode, knotc doesn't report processing
283 errors. The OK response to triggering commands means that the com‐
284 mand has been successfully sent to the server. To verify if the oper‐
285 ation succeeded, it's necessary to check the server log.
286 Actions zone-flush, zone-backup, and zone-restore are carried out by
288 the knotd process. The directory specified must be accessible to the
289 user account that knotd runs under and if the directory already exists,
290 its permissions must be appropriate for that user account.
291 Interactive mode
293 The utility provides interactive mode with basic line editing function‐
294 ality, command completion, and command history.
295 Interactive mode behavior can be customized in ~/.editrc. Refer to ed‐
297 itrc(5) for details.
298 Command history is saved in ~/.knotc_history.
300
302 Exit status of 0 means successful operation. Any other exit status in‐
303 dicates an error.
304
306 Reload the whole server configuration
307 $ knotc reload
308 Flush the example.com and example.org zones
310 $ knotc zone-flush example.com example.org
311 Get the current server configuration
313 $ knotc conf-read server
314 Get the list of the current zones
316 $ knotc conf-read zone.domain
317 Get the primary servers for the example.com zone
319 $ knotc conf-read 'zone[example.com].master'
320 Add example.org zone with a zonefile location
322 $ knotc conf-begin
323 $ knotc conf-set 'zone[example.org]'
324 $ knotc conf-set 'zone[example.org].file' '/var/zones/example.org.zone'
325 $ knotc conf-commit
326 Get the SOA record for each configured zone
328 $ knotc zone-read -- @ SOA
329
331 knotd(8), knot.conf(5), editrc(5).
332
334 CZ.NIC Labs <https://www.knot-dns.cz>
335
337 Copyright 2010–2022, CZ.NIC, z.s.p.o.
3383.1.8 2022-04-28 KNOTC(8)