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-status zone [filter]
73 Show the zone status. Filters are +role, +serial, +transaction,
74 +events, and +freeze.
75 zone-check [zone...]
77 Test if the server can load the zone. Semantic checks are exe‐
78 cuted if enabled in the configuration. If invoked with the force
79 option, an error is returned when semantic check warning ap‐
80 pears. (*)
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-read zone [owner [type]]
169 Get zone data that are currently being presented.
170 zone-begin zone...
172 Begin a zone transaction.
173 zone-commit zone...
175 Commit the zone transaction. All changes are applied to the
176 zone.
177 zone-abort zone...
179 Abort the zone transaction. All changes are discarded.
180 zone-diff zone
182 Get zone changes within the transaction.
183 zone-get zone [owner [type]]
185 Get zone data within the transaction.
186 zone-set zone owner [ttl] type rdata
188 Add zone record within the transaction. The first record in a
189 rrset requires a ttl value specified.
190 zone-unset zone owner [type [rdata]]
192 Remove zone data within the transaction.
193 zone-purge zone... [filter...]
195 Purge zone data, zone file, journal, timers, and/or KASP data of
196 specified zones. Available filters are +expire, +zonefile,
197 +journal, +timers, and +kaspdb. If no filter is specified, all
198 filters are enabled. If the zone is no longer configured, add
199 +orphan filter (zone file cannot be purged in this case). (#)
200 zone-stats zone [module[.counter]]
202 Show zone statistics counter(s). To print also counters with
203 value 0, use force option.
204 conf-init
206 Initialize the configuration database. If the database doesn't
207 exist yet, execute this command as an intended user to ensure
208 the server is permitted to access the database (e.g. sudo -u
209 knot knotc conf-init). (*)
210 conf-check
212 Check the server configuration. (*)
213 conf-import filename
215 Import a configuration file into the configuration database. If
216 the database doesn't exist yet, execute this command as an in‐
217 tended user to ensure the server is permitted to access the
218 database (e.g. sudo -u knot knotc conf-import ...). Also ensure
219 the server is not using the configuration database at the same
220 time! (*)
221 conf-export [filename]
223 Export the configuration database into a config file or stdout.
224 (*)
225 conf-list [item]
227 List the configuration database sections or section items.
228 conf-read [item]
230 Read the item from the active configuration database.
231 conf-begin
233 Begin a writing configuration database transaction. Only one
234 transaction can be opened at a time.
235 conf-commit
237 Commit the configuration database transaction.
238 conf-abort
240 Rollback the configuration database transaction.
241 conf-diff [item]
243 Get the item difference in the transaction.
244 conf-get [item]
246 Get the item data from the transaction.
247 conf-set item [data...]
249 Set the item data in the transaction.
250 conf-unset [item] [data...]
252 Unset the item data in the transaction.
253 Notes
255 Empty or -- zone parameter means all zones or all zones with a transac‐
256 tion.
257 Use @ owner to denote the zone name.
259 Type item parameter in the form of section[[id]][.name].
261 (*) indicates a local operation which requires a configuration.
263 (#) indicates an optionally blocking operation.
265 The -b and -f options can be placed right after the command name.
267 Responses returned by knotc commands depend on the mode:
269 • In the blocking mode, knotc reports if an error occurred during pro‐
271 cessing of the command by the server. If an error is reported, a more
272 detailed information about the failure can usually be found in the
273 server log.
274 • In the non-blocking (default) mode, knotc doesn't report processing
276 errors. The OK response to triggering commands means that the com‐
277 mand has been successfully sent to the server. To verify if the oper‐
278 ation succeeded, it's necessary to check the server log.
279 Actions zone-flush, zone-backup, and zone-restore are carried out by
281 the knotd process. The directory specified must be accessible to the
282 user account that knotd runs under and if the directory already exists,
283 its permissions must be appropriate for that user account.
284 Interactive mode
286 The utility provides interactive mode with basic line editing function‐
287 ality, command completion, and command history.
288 Interactive mode behavior can be customized in ~/.editrc. Refer to ed‐
290 itrc(5) for details.
291 Command history is saved in ~/.knotc_history.
293
295 Exit status of 0 means successful operation. Any other exit status in‐
296 dicates an error.
297
299 Reload the whole server configuration
300 $ knotc reload
301 Flush the example.com and example.org zones
303 $ knotc zone-flush example.com example.org
304 Get the current server configuration
306 $ knotc conf-read server
307 Get the list of the current zones
309 $ knotc conf-read zone.domain
310 Get the primary servers for the example.com zone
312 $ knotc conf-read 'zone[example.com].master'
313 Add example.org zone with a zonefile location
315 $ knotc conf-begin
316 $ knotc conf-set 'zone[example.org]'
317 $ knotc conf-set 'zone[example.org].file' '/var/zones/example.org.zone'
318 $ knotc conf-commit
319 Get the SOA record for each configured zone
321 $ knotc zone-read -- @ SOA
322
324 knotd(8), knot.conf(5), editrc(5).
325
327 CZ.NIC Labs <https://www.knot-dns.cz>
328
330 Copyright 2010–2021, CZ.NIC, z.s.p.o.
3313.1.4 2021-11-04 KNOTC(8)