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

3 4
knotc – Knot DNS control utility
================================
Jan Včelák's avatar
Jan Včelák committed
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

Jan Včelák's avatar
Jan Včelák committed
16 17 18 19
Parameters
..........

**-c**, **--config** *file*
20
  Use a textual configuration file (default is :file:`@config_dir@/knot.conf`).
Jan Včelák's avatar
Jan Včelák committed
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.
Jan Včelák's avatar
Jan Včelák committed
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).
Jan Včelák's avatar
Jan Včelák committed
32 33

**-f**, **--force**
34
  Forced operation. Overrides some checks.
Jan Včelák's avatar
Jan Včelák committed
35 36

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

**-h**, **--help**
  Print the program help.
Jan Včelák's avatar
Jan Včelák committed
41 42

**-V**, **--version**
43
  Print the program version.
Jan Včelák's avatar
Jan Včelák committed
44 45 46 47

Actions
.......

48 49
**status**
  Check if the server is running.
Jan Včelák's avatar
Jan Včelák committed
50 51

**stop**
52
  Stop the server if running.
Jan Včelák's avatar
Jan Včelák committed
53

54
**reload**
55 56
  Reload the server configuration and modified zone files. All open zone
  transactions will be aborted!
Jan Včelák's avatar
Jan Včelák committed
57

Filip Siroky's avatar
Filip Siroky committed
58 59 60 61
**stats** [*module*\ [\ **.**\ *counter*\ ]]
  Show global statistics counter(s). To print also counters with value 0, use
  force option.

62
**zone-check** [*zone*...]
63 64
  Test if the server can load the zone. Semantic checks are executed if enabled
  in the configuration. (*)
65 66 67 68 69

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

**zone-reload** [*zone*...]
70 71
  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,
72 73
  the notification of slave servers is scheduled. An open zone transaction
  will be aborted!
Jan Včelák's avatar
Jan Včelák committed
74

75
**zone-refresh** [*zone*...]
76 77
  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.
Jan Včelák's avatar
Jan Včelák committed
78

79
**zone-retransfer** [*zone*...]
80 81
  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.
Jan Včelák's avatar
Jan Včelák committed
82

83 84
**zone-flush** [*zone*...]
  Trigger a zone journal flush into the zone file.
Jan Včelák's avatar
Jan Včelák committed
85

Daniel Salzman's avatar
Daniel Salzman committed
86
**zone-sign** [*zone*...]
87 88
  Trigger a DNSSEC re-sign of the zone. Existing signatures will be dropped.
  This command is valid for zones with automatic DNSSEC signing.
Jan Včelák's avatar
Jan Včelák committed
89

90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114
**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.

Daniel Salzman's avatar
Daniel Salzman committed
115
**zone-purge** *zone*...
116
  Purge zone data, file, journal, and timers.
Daniel Salzman's avatar
Daniel Salzman committed
117

Filip Siroky's avatar
Filip Siroky committed
118 119 120 121
**zone-stats** *zone* [*module*\ [\ **.**\ *counter*\ ]]
  Show zone statistics counter(s). To print also counters with value 0, use
  force option.

122 123 124 125
**zone-status** *zone* [*filter*]
  Show the zone status. (*)
  Filters are type, serial, next-event, auto-dnssec, transaction, event-timers.

126 127 128 129 130 131 132
**zone-freeze** [*zone*...]
  Temporarily postpone zone-changing events (load, refresh, update, flush, and
  DNSSEC signing).

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

133
**conf-init**
Daniel Salzman's avatar
Daniel Salzman committed
134
  Initialize the configuration database. (*)
135 136 137

**conf-check**
  Check the server configuration. (*)
Jan Včelák's avatar
Jan Včelák committed
138

139
**conf-import** *filename*
Daniel Salzman's avatar
Daniel Salzman committed
140 141
  Import a configuration file into the configuration database. Ensure the
  server is not using the configuration database! (*)
Jan Včelák's avatar
Jan Včelák committed
142

143
**conf-export** *filename*
Daniel Salzman's avatar
Daniel Salzman committed
144
  Export the configuration database into a config file. (*)
145

146
**conf-list** [*item*]
Daniel Salzman's avatar
Daniel Salzman committed
147
  List the configuration database sections or section items.
148 149

**conf-read** [*item*]
Daniel Salzman's avatar
Daniel Salzman committed
150
  Read the item from the active configuration database.
151 152

**conf-begin**
Daniel Salzman's avatar
Daniel Salzman committed
153 154
  Begin a writing configuration database transaction. Only one transaction
  can be opened at a time.
155 156

**conf-commit**
Daniel Salzman's avatar
Daniel Salzman committed
157
  Commit the configuration database transaction.
158 159

**conf-abort**
Daniel Salzman's avatar
Daniel Salzman committed
160
  Rollback the configuration database transaction.
161 162

**conf-diff** [*item*]
163
  Get the item difference in the transaction.
164 165

**conf-get** [*item*]
166
  Get the item data from the transaction.
167 168

**conf-set** *item* [*data*...]
169
  Set the item data in the transaction.
170 171

**conf-unset** [*item*] [*data*...]
172
  Unset the item data in the transaction.
Jan Včelák's avatar
Jan Včelák committed
173

174
Note
175
....
Jan Včelák's avatar
Jan Včelák committed
176

177 178 179
Empty or **--** *zone* parameter means all zones or all zones with a transaction.

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

181
Type *item* parameter in the form of *section*\ [**[**\ *id*\ **]**\ ][**.**\ *name*].
182

Daniel Salzman's avatar
Daniel Salzman committed
183
(*) indicates a local operation which requires a configuration.
Jan Včelák's avatar
Jan Včelák committed
184

185 186 187 188 189 190 191 192 193 194 195
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`.

196 197
Examples
--------
Jan Včelák's avatar
Jan Včelák committed
198

199 200
Reload the whole server configuration
.....................................
Jan Včelák's avatar
Jan Včelák committed
201 202 203

::

204
  $ knotc reload
Jan Včelák's avatar
Jan Včelák committed
205

Daniel Salzman's avatar
Daniel Salzman committed
206 207
Flush the example.com and example.org zones
...........................................
Jan Včelák's avatar
Jan Včelák committed
208 209 210

::

Daniel Salzman's avatar
Daniel Salzman committed
211
  $ knotc zone-flush example.com example.org
Jan Včelák's avatar
Jan Včelák committed
212

213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231
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
...............................................

::

232
  $ knotc conf-read 'zone[example.com].master'
233

Daniel Salzman's avatar
Daniel Salzman committed
234 235
Add example.org zone with a zonefile location
.............................................
236 237 238 239

::

  $ knotc conf-begin
240 241
  $ knotc conf-set 'zone[example.org]'
  $ knotc conf-set 'zone[example.org].file' '/var/zones/example.org.zone'
242 243
  $ knotc conf-commit

244 245 246 247 248 249 250
Get the SOA record for each configured zone
...........................................

::

  $ knotc zone-read -- @ SOA

Jan Včelák's avatar
Jan Včelák committed
251 252 253
See Also
--------

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