1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
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
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
|
@node Running Knot DNS, Troubleshooting, Knot DNS Configuration, Top
@chapter Running Knot DNS
@menu
* Running a slave server::
* Running a master server::
* Controlling running daemon::
@end menu
Knot DNS is designed to compile zone files before loading them into server.
The reason for this is to speed up server startup, but requires a bit of user
effort, so each time the zone file changes you need to compile it.
@example
$ knotc -c knot.conf compile
@end example
Or alternatively, you can compile automatically using the @code{-a} flag.
@example
$ knotc -a -c knot.conf start|reload|restart
@end example
The tool @code{knotc} is designed as a front-end for user, making it easier
to do everything from zone compilation to controlling the server daemon.
To communicate with the binary, it reads the PID from the @emph{PID file} specified in the configuration @code{pidfile} and sends POSIX signals to it (@pxref{pidfile}).
If you want to control the daemon directly, use @code{SIGINT} to quit the process or @code{SIGHUP} to reload configuration. Signal @code{SIGUSR2} is currently used to refresh slave zones.
@example
Usage: knotc [parameters] start|stop|restart|reload|running|compile
Parameters:
-c [file], --config=[file]
Select configuration file.
-j [num], --jobs=[num]
Number of parallel tasks to run when compiling.
-f, --force
Force operation - override some checks.
-v, --verbose
Verbose mode - additional runtime information.
-V, --version
Print knot server version.
-w, --wait
Wait for the server to finish start/stop operations.
-i, --interactive
Interactive mode (do not daemonize).
-a, --auto
Enable automatic recompilation (start or reload).
-h, --help
Print help and usage.
Actions:
start Start knot server zone (no-op if running).
stop Stop knot server (no-op if not running).
restart Stops and then starts knot server.
reload Reload knot configuration and compiled zones.
refresh Refresh all slave zones.
running Check if server is running.
checkconf Check server configuration.
checkzone Check zones (accepts specific zones,
e.g. 'knotc checkzone example1.com example2.com').
compile Compile zones (accepts specific zones, see above).
@end example
If you want to run Knot DNS daemon directly, you can use @code{knotd} binary
to do that. It accepts just configuration file and option to run in background.
@example
Usage: knotd [parameters]
Parameters:
-c, --config [file] Select configuration file.
-d, --daemonize Run server as a daemon.
-v, --verbose Verbose mode - additional runtime information.
-V, --version Print version of the server.
-h, --help Print help and usage.
@end example
Also, the server needs to create several files in order to run properly.
All files are placed in the directory described by @code{storage} (@pxref{storage}).
PID file can be placed elsewhere using the @code{pidfile} statement (@pxref{pidfile}).
Slave zones with relative path specified will be placed in the @code{storage} as well.
@itemize @bullet
@item
@emph{Compiled zones} - preprocessed zones, for example zone @code{example.com} will be
placed in @file{STORAGE/example.com.db}.
@item
@emph{Journal files} - each zone has a journal file to store differences for IXFR and
dynamic updates. Journal for zone @code{example.com} will be
placed in @file{STORAGE/example.com.diff.db}.
@item
@emph{PID file} - unless specified differently by the @code{pidfile}, it will be placed
in the @file{STORAGE/knot.pid}.
@item
@emph{Checksum files} - in order to identify compiled zone corruption, it
has a separate checksum file. For @code{example.com} will be
placed in @file{STORAGE/example.com.db.crc}.
@end itemize
@node Running a slave server
@section Running a slave server
Running the server as a slave is very straightforward as you usually bootstrap
zones over AXFR and thus avoid any manual zone compilation.
When a zone is transferred over AXFR, both the compiled zone and the zone file is
updated, so no further compilation is needed.
However when IXFR transfer finishes, it stores the differences in a journal file
and doesn't update the zone file nor compiled zone immediately,
but there is a timer that checks periodically for new differences and
updates both zone file and the compiled zone. You can configure this timer
with the @code{zonefile-sync} statement in @code{zones} (@pxref{zones}).
There are two ways to start the server - directly or with the @code{knotc} controller tool.
First, let us start it directly. If you do not pass any configuration, it will try to
search configuration in default path that is @code{SYSCONFDIR/knot.conf}. The @code{SYSCONFDIR}
depends on what you passed to the @code{./configure}, usually @code{/etc}.
@example
$ knotc -c slave.conf checkconf # check configuration
$ knotd -c slave.conf
@end example
However to start it as a daemon, @code{knotc} tool should be used.
The @code{knotc} tool accepts parameter @code{-w} to wait until the requested operation finishes.
When the action is "start" for example, it waits until the server starts to serve zones.
@example
$ knotc -w -c slave.conf start # start the daemon
$ knotc -c slave.conf stop # stop the daemon
@end example
When the server is running, you can control the daemon, see @ref{Controlling running daemon}.
@node Running a master server
@section Running a master server
Knot DNS first needs to compile the zones before it can load them, therefore you need to
compile them with the @code{knotc compile} action or use flag @code{-a} to compile the zones automatically.
If you want to just check the zone files first before starting,
you can use @code{knotc checkzone} action.
@example
$ knotc -c master.conf checkzone example.com
@end example
Starting and stopping the daemon is the same as with the slave server in the previous section.
@example
$ knotc -c master.conf compile
$ knotc -w -c master.conf start
@end example
Or you can compile it automatically:
@example
$ knotc -c master.conf checkconf # check configuration
$ knotc -a -w -c master.conf start
@end example
@node Controlling running daemon
@section Controlling running daemon
Knot DNS was designed to allow server reconfiguration on-the-fly without interrupting
its operation. Thus it is possible to change both configuration and zone files and
also add or remove zones without restarting the server. This can be done with the
@code{knotc reload} action.
@example
$ knotc -c master.conf compile # compile updated zones
$ knotc -c master.conf reload # reconfigure and load updated zones
@end example
Or use the @code{-a} again.
@example
$ knotc -a -c master.conf reload # compile zones and reconfigure
@end example
If you want @emph{IXFR-out} differences created from changes you make to a zone file, enable @code{ixfr-from-differences}
in @code{zones} statement, then compile the zone and reload your server as seen above.
If @emph{SOA}'s @emph{serial} is not changed no differences will be created. Please note
that this feature is in @emph{experimental} stage and should be used with care.
If you encounter a bug using this feature, please send it to Knot developers (@pxref{Submitting a bugreport}).
You can also choose to tear-down the server fully and restart with the @code{knotc restart} action.
@example
$ knotc -c master.conf running # check if running
$ knotc -c master.conf restart # fully restart
@end example
If you want to force refresh the slave zones, you can do this with the @code{knotc refresh} action.
@example
$ knotc -c slave.conf refresh
@end example
For a complete list of actions refer to @code{knotc --help} command output.
|
