man_knotc.rst 7.39 KB
Newer Older
1 2
.. highlight:: console

3 4
knotc – Knot DNS control utility
================================
5 6 7 8 9 10 11 12 13

Synopsis
--------

:program:`knotc` [*parameters*] *action* [*action_args*]

Description
-----------

14
If no *action* is specified, the program is executed in interactive mode.
15

16 17 18 19
Parameters
..........

**-c**, **--config** *file*
20
  Use a textual configuration file (default is :file:`@config_dir@/knot.conf`).
21 22

**-C**, **--confdb** *directory*
23 24 25
  Use a binary configuration database directory (default is :file:`@storage_dir@/confdb`).
  The default configuration database, if exists, has a preference to the default
  configuration file.
26

27
**-s**, **--socket** *path*
28 29 30 31
  Use a control UNIX socket path (default is :file:`@run_dir@/knot.sock`).

**-t**, **--timeout** *seconds*
  Use a control timeout in seconds. Set 0 for infinity (default is 5).
32 33

**-f**, **--force**
34
  Forced operation. Overrides some checks.
35 36

**-v**, **--verbose**
37 38 39 40
  Enable debug output.

**-h**, **--help**
  Print the program help.
41 42

**-V**, **--version**
43
  Print the program version.
44 45 46 47

Actions
.......

48
**status** [*detail*]
49 50 51
  Check if the server is running. Details are **version** for the running
  server version, **workers** for the numbers of worker threads,
  or **configure** for the configure summary.
52 53

**stop**
54
  Stop the server if running.
55

56
**reload**
57 58
  Reload the server configuration and modified zone files. All open zone
  transactions will be aborted!
59

60 61 62 63
**stats** [*module*\ [\ **.**\ *counter*\ ]]
  Show global statistics counter(s). To print also counters with value 0, use
  force option.

64
**zone-status** *zone* [*filter*]
65 66
  Show the zone status. Filters are **+role**, **+serial**, **+transaction**,
  **+events**, and **+freeze**.
67

68
**zone-check** [*zone*...]
69 70
  Test if the server can load the zone. Semantic checks are executed if enabled
  in the configuration. (*)
71 72 73 74 75

**zone-memstats** [*zone*...]
  Estimate memory use for the zone. (*)

**zone-reload** [*zone*...]
76 77
  Trigger a zone reload from a disk without checking its modification time. For
  slave zone, the refresh from a master server is scheduled; for master zone,
78 79
  the notification of slave servers is scheduled. An open zone transaction
  will be aborted!
80

81
**zone-refresh** [*zone*...]
82 83
  Trigger a check for the zone serial on the zone's master. If the master has a
  newer zone, a transfer is scheduled. This command is valid for slave zones.
84

85
**zone-retransfer** [*zone*...]
86 87
  Trigger a zone transfer from the zone's master. The server doesn't check the
  serial of the master's zone. This command is valid for slave zones.
88

89 90 91 92
**zone-notify** [*zone*...]
  Trigger a NOTIFY message to all configured remotes. This can help in cases
  when previous NOTIFY had been lost or the slaves offline.

93 94 95 96
**zone-flush** [*zone*...] [**+outdir** *directory*]
  Trigger a zone journal flush into the zone file. If output dir is specified,
  instead of flushing the zonefile, the zone is dumped to a file in the specified
  directory.
97

Daniel Salzman's avatar
Daniel Salzman committed
98
**zone-sign** [*zone*...]
99 100
  Trigger a DNSSEC re-sign of the zone. Existing signatures will be dropped.
  This command is valid for zones with automatic DNSSEC signing.
101

102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126
**zone-read** *zone* [*owner* [*type*]]
  Get zone data that are currently being presented.

**zone-begin** *zone*...
  Begin a zone transaction.

**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.

127
**zone-purge** *zone*... [*filter*...]
128 129 130 131 132
  Purge zone data, zone file, journal, timers, and/or KASP data of specified zones.
  Available filters are **+expire**, **+zonefile**, **+journal**, **+timers**,
  and **+kaspdb**. If no filter is specified, all filters are enabled.
  It the zone is no longer configured, add **+orphan** filter (zone file cannot
  be purged in this case).
133

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

138 139 140 141 142 143 144
**zone-freeze** [*zone*...]
  Temporarily postpone zone-changing events (load, refresh, update, flush, and
  DNSSEC signing).

**zone-thaw** [*zone*...]
  Dismiss zone freeze.

145 146 147 148 149
**zone-ksk-submitted** *zone*
  Use when the zone's KSK rollover is in submittion phase. By calling this command
  the user confirms manually that the parent zone contains DS record for the new
  KSK in submission phase and the old KSK can be retired.

150
**conf-init**
Daniel Salzman's avatar
Daniel Salzman committed
151
  Initialize the configuration database. (*)
152 153 154

**conf-check**
  Check the server configuration. (*)
155

156
**conf-import** *filename*
Daniel Salzman's avatar
Daniel Salzman committed
157 158
  Import a configuration file into the configuration database. Ensure the
  server is not using the configuration database! (*)
159

160 161
**conf-export** [*filename*]
  Export the configuration database into a config file or stdout. (*)
162

163
**conf-list** [*item*]
Daniel Salzman's avatar
Daniel Salzman committed
164
  List the configuration database sections or section items.
165 166

**conf-read** [*item*]
Daniel Salzman's avatar
Daniel Salzman committed
167
  Read the item from the active configuration database.
168 169

**conf-begin**
Daniel Salzman's avatar
Daniel Salzman committed
170 171
  Begin a writing configuration database transaction. Only one transaction
  can be opened at a time.
172 173

**conf-commit**
Daniel Salzman's avatar
Daniel Salzman committed
174
  Commit the configuration database transaction.
175 176

**conf-abort**
Daniel Salzman's avatar
Daniel Salzman committed
177
  Rollback the configuration database transaction.
178 179

**conf-diff** [*item*]
180
  Get the item difference in the transaction.
181 182

**conf-get** [*item*]
183
  Get the item data from the transaction.
184 185

**conf-set** *item* [*data*...]
186
  Set the item data in the transaction.
187 188

**conf-unset** [*item*] [*data*...]
189
  Unset the item data in the transaction.
190

191
Note
192
....
193

194 195 196
Empty or **--** *zone* parameter means all zones or all zones with a transaction.

Use **@** *owner* to denote the zone name.
197

198
Type *item* parameter in the form of *section*\ [**[**\ *id*\ **]**\ ][**.**\ *name*].
199

Daniel Salzman's avatar
Daniel Salzman committed
200
(*) indicates a local operation which requires a configuration.
201

202 203 204 205 206 207 208 209 210 211 212
Interactive mode
................

The utility provides interactive mode with basic line editing functionality,
command completion, and command history.

Interactive mode behavior can be customized in `~/.editrc`. Refer to
:manpage:`editrc(5)` for details.

Command history is saved in `~/.knotc_history`.

213 214
Examples
--------
215

216 217
Reload the whole server configuration
.....................................
218 219 220

::

221
  $ knotc reload
222

Daniel Salzman's avatar
Daniel Salzman committed
223 224
Flush the example.com and example.org zones
...........................................
225 226 227

::

Daniel Salzman's avatar
Daniel Salzman committed
228
  $ knotc zone-flush example.com example.org
229

230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248
Get the current server configuration
....................................

::

  $ knotc conf-read server

Get the list of the current zones
.................................

::

  $ knotc conf-read zone.domain

Get the master remotes for the example.com zone
...............................................

::

249
  $ knotc conf-read 'zone[example.com].master'
250

Daniel Salzman's avatar
Daniel Salzman committed
251 252
Add example.org zone with a zonefile location
.............................................
253 254 255 256

::

  $ knotc conf-begin
257 258
  $ knotc conf-set 'zone[example.org]'
  $ knotc conf-set 'zone[example.org].file' '/var/zones/example.org.zone'
259 260
  $ knotc conf-commit

261 262 263 264 265 266 267
Get the SOA record for each configured zone
...........................................

::

  $ knotc zone-read -- @ SOA

268 269 270
See Also
--------

271
:manpage:`knotd(8)`, :manpage:`knot.conf(5)`, :manpage:`editrc(5)`.