1REC_CONTROL(1) PowerDNS Recursor REC_CONTROL(1)
2
6 rec_control - Command line tool to control a running Recursor
7
9 rec_control [OPTION]... COMMAND [COMMAND-OPTION]...
10
12 rec_control allows the operator to query and control a running instance
13 of the PowerDNS Recursor.
14 rec_control talks to the recursor via a the 'controlsocket'. Which is
16 usually located in /var/run . The --socket-dir or the --config-dir and
17 --config-name switches control to which process rec_control connects.
18
20 To see if the Recursor is alive, run:
21 # rec_control ping
23 To stop the recursor by hand, run:
25 # rec_control quit
27 To dump the cache to disk, execute:
29 # rec_control dump-cache /tmp/the-cache
31
33 --help provide this helpful message.
34 --config-dir=<path>
36 Directory where the recursor.conf lives.
37 --config-name=<name>
39 Name of the virtual configuration.
40 --socket-dir=<path>
42 Where the controlsocket will live, please use --config-dir in‐
43 stead.
44 --socket-pid=<pid>
46 When running in SMP mode, pid of pdns_recursor to control.
47 --timeout=<num>
49 Number of seconds to wait for the remote PowerDNS Recursor to
50 respond.
51
53 add-dont-throttle-names NAME [NAME...]
54 Add names for nameserver domains that may not be throttled.
55 add-dont-throttle-netmasks NETMASK [NETMASK...]
57 Add netmasks for nameservers that may not be throttled.
58 add-nta DOMAIN [REASON]
60 Add a Negative Trust Anchor for DOMAIN, suffixed optionally with
61 REASON.
62 add-ta DOMAIN DSRECORD
64 Add a Trust Anchor for DOMAIN with DS record data DSRECORD. This
65 adds the new Trust Anchor to the existing set of Trust Anchors
66 for DOMAIN.
67 current-queries
69 Shows the currently active queries.
70 clear-dont-throttle-names NAME [NAME...]
72 Remove names that are not allowed to be throttled. If NAME is
73 '*', remove all
74 clear-dont-throttle-netmasks NETMASK [NETMASK...]
76 Remove netmasks that are not allowed to be throttled. If NETMASK
77 is '*', remove all
78 clear-nta DOMAIN...
80 Remove Negative Trust Anchor for one or more DOMAINs. Set domain
81 to '*' to remove all NTA's.
82 clear-ta [DOMAIN]...
84 Remove Trust Anchor for one or more DOMAINs. Note that removing
85 the root trust anchor is not possible.
86 dump-cache FILENAME
88 Dumps the entire cache to FILENAME. This file should not exist
89 already, PowerDNS will refuse to overwrite it. While dumping,
90 the recursor will not answer questions.
91 Typical PowerDNS Recursors run multiple threads, therefore
93 you'll see duplicate, different entries for the same domains.
94 The negative cache is also dumped to the same file. The
95 per-thread positive and negative cache dumps are separated with
96 an appropriate comment.
97 NOTE:
99 pdns_recursor often runs in a chroot. You can retrieve the
100 file using:
101 rec_control dump-cache /tmp/file
103 mv /proc/$(pidof pdns_recursor)/root/tmp/file /tmp/filename
104 dump-edns FILENAME
106 Dumps the EDNS status to the filename mentioned. This file
107 should not exist already, PowerDNS will refuse to overwrite it.
108 While dumping, the recursor will not answer questions.
109 NOTE:
111 pdns_recursor often runs in a chroot. You can retrieve the
112 file using:
113 rec_control dump-edns /tmp/file
115 mv /proc/$(pidof pdns_recursor)/root/tmp/file /tmp/filename
116 dump-nsspeeds FILENAME
118 Dumps the nameserver speed statistics to the FILENAME mentioned.
119 This file should not exist already, PowerDNS will refuse to
120 overwrite it. While dumping, the recursor will not answer ques‐
121 tions. Statistics are kept per thread, and the dumps end up in
122 the same file.
123 NOTE:
125 pdns_recursor often runs in a chroot. You can retrieve the
126 file using:
127 rec_control dump-nsspeeds /tmp/file
129 mv /proc/$(pidof pdns_recursor)/root/tmp/file /tmp/filename
130 dump-rpz ZONE NAME FILE NAME
132 Dumps the content of the RPZ zone named ZONE NAME to the FILE‐
133 NAME mentioned. This file should not exist already, PowerDNS
134 will refuse to overwrite it otherwise. While dumping, the recur‐
135 sor will not answer questions.
136 NOTE:
138 pdns_recursor often runs in a chroot. You can retrieve the
139 file using:
140 rec_control dump-rpz ZONE_NAME /tmp/file
142 mv /proc/$(pidof pdns_recursor)/root/tmp/file /tmp/filename
143 dump-throttlemap FILENAME
145 Dump the contents of the throttle map to the FILENAME mentioned.
146 This file should not exist already, PowerDNS will refuse to
147 overwrite it otherwise. While dumping, the recursor will not an‐
148 swer questions.
149 NOTE:
151 pdns_recursor often runs in a chroot. You can retrieve the
152 file using:
153 rec_control dump-throttlemap /tmp/file
155 mv /proc/$(pidof pdns_recursor)/root/tmp/file /tmp/filename
156 dump-failedservers FILENAME
158 Dump the contents of the failed server map to the FILENAME men‐
159 tioned. This file should not exist already, PowerDNS will
160 refuse to overwrite it otherwise. While dumping, the recursor
161 will not answer questions.
162 NOTE:
164 pdns_recursor often runs in a chroot. You can retrieve the
165 file using:
166 rec_control dump-failedservers /tmp/file
168 mv /proc/$(pidof pdns_recursor)/root/tmp/file /tmp/filename
169 get STATISTIC [STATISTIC]...
171 Retrieve a statistic. For items that can be queried, see ../met‐
172 rics
173 get-all
175 Retrieve all known statistics.
176 get-dont-throttle-names
178 Get the list of names that are not allowed to be throttled.
179 get-dont-throttle-netmasks
181 Get the list of netmasks that are not allowed to be throttled.
182 get-ntas
184 Get a list of the currently configured Negative Trust Anchors.
185 get-tas
187 Get a list of the currently configured Trust Anchors.
188 get-parameter KEY [KEY]...
190 Retrieves the specified configuration parameter(s).
191 get-qtypelist
193 Retrieves QType statistics. Queries from cache aren't being
194 counted yet.
195 help Shows a list of supported commands understood by the running
197 pdns_recursor
198 ping Check if server is alive.
200 quit Request shutdown of the recursor, exiting the process while let‐
202 ting the OS clean up resources.
203 quit-nicely
205 Request nice shutdown of the recursor. This method allows all
206 threads to finish their current work and releases resources be‐
207 fore exiting. This is the preferred method to stop the recursor.
208 reload-acls
210 Reloads ACLs.
211 reload-lua-script [FILENAME]
213 (Re)loads Lua script FILENAME. If FILENAME is empty, attempt to
214 reload the currently loaded script. This replaces the script
215 currently loaded.
216 reload-lua-config [FILENAME]
218 (Re)loads Lua configuration FILENAME. If FILENAME is empty, at‐
219 tempt to reload the currently loaded file. Note that FILENAME
220 will be fully executed, any settings changed at runtime that are
221 not modified in this file, will still be active. Reloading RPZ,
222 especially by AXFR, can take some time; during which the recur‐
223 sor will not answer questions.
224 reload-zones
226 Reload authoritative and forward zones. Retains current configu‐
227 ration in case of errors.
228 set-carbon-server CARBON SERVER [CARBON OURNAME]
230 Set the carbon-server setting to CARBON SERVER. If CARBON OUR‐
231 NAME is not empty, also set the carbon-ourname setting to CARBON
232 OURNAME.
233 set-dnssec-log-bogus SETTING
235 Set dnssec-log-bogus setting to SETTING. Set to 'on' or 'yes' to
236 log DNSSEC validation failures and to 'no' or 'off' to disable
237 logging these failures.
238 set-ecs-minimum-ttl NUM
240 Set ecs-minimum-ttl-override to NUM.
241 set-max-cache-entries NUM
243 Change the maximum number of entries in the DNS cache. If re‐
244 duced, the cache size will start shrinking to this number as
245 part of the normal cache purging process, which might take a
246 while.
247 set-max-packetcache-entries NUM
249 Change the maximum number of entries in the packet cache. If
250 reduced, the cache size will start shrinking to this number as
251 part of the normal cache purging process, which might take a
252 while.
253 set-minimum-ttl NUM
255 Set minimum-ttl-override to NUM.
256 top-queries
258 Shows the top-20 queries. Statistics are over the last
259 'stats-ringbuffer-entries' queries.
260 top-pub-queries
262 Shows the top-20 queries grouped by public suffix list. Statis‐
263 tics are over the last 'stats-ringbuffer-entries' queries.
264 top-largeanswer-remotes
266 Shows the top-20 remote hosts causing large answers. Statistics
267 are over the last 'stats-ringbuffer-entries' queries.
268 top-remotes
270 Shows the top-20 most active remote hosts. Statistics are over
271 the last 'stats-ringbuffer-entries' queries.
272 top-servfail-queries
274 Shows the top-20 queries causing servfail responses. Statistics
275 are over the last 'stats-ringbuffer-entries' queries.
276 top-bogus-queries
278 Shows the top-20 queries causing bogus responses. Statistics are
279 over the last 'stats-ringbuffer-entries' queries.
280 top-pub-servfail-queries
282 Shows the top-20 queries causing servfail responses grouped by
283 public suffix list. Statistics are over the last 'stats-ring‐
284 buffer-entries' queries.
285 top-pub-bogus-queries
287 Shows the top-20 queries causing bogus responses grouped by pub‐
288 lic suffix list. Statistics are over the last 'stats-ring‐
289 buffer-entries' queries.
290 top-servfail-remotes
292 Shows the top-20 most active remote hosts causing servfail re‐
293 sponses. Statistics are over the last 'stats-ringbuffer-en‐
294 tries' queries.
295 top-bogus-remotes
297 Shows the top-20 most active remote hosts causing bogus re‐
298 sponses. Statistics are over the last 'stats-ringbuffer-en‐
299 tries' queries.
300 top-timeouts
302 Shows the top-20 most active downstream timeout destinations.
303 Statistics are over the last 'stats-ringbuffer-entries' queries.
304 trace-regex REGEX
306 Emit resolution trace for matching queries. Empty regex to dis‐
307 able trace.
308 Queries matching this regular expression will generate volumi‐
310 nous tracing output. Be aware that matches from the packet cache
311 will still not generate tracing. To unset the regex, pass
312 trace-regex without a new regex.
313 The regular expression is matched against domain queries termi‐
315 nated with a dot. For example the regex 'powerdns.com$' will not
316 match a query for 'www.powerdns.com', since the attempted match
317 will be with 'www.powerdns.com.'.
318 In addition, since this is a regular expression, to exclusively
320 match queries for 'www.powerdns.com', one should escape the
321 dots: '^www\.powerdns\.com\.$'. Note that the single quotes
322 prevent further interpretation of the backslashes by the shell.
323 Multiple matches can be chained with the | operator. For exam‐
325 ple, to match all queries for Dutch (.nl) and German (.de) do‐
326 main names, use: '\.nl\.$|\.de\.$'.
327 unload-lua-script
329 Unloads Lua script if one was loaded.
330 version
332 Report running version.
333 wipe-cache DOMAIN [DOMAIN] [...]
335 Wipe entries for DOMAIN (exact name match) from the cache. This
336 is useful if, for example, an important server has a new IP ad‐
337 dress, but the TTL has not yet expired. Multiple domain names
338 can be passed. DOMAIN can be suffixed with a '$'. to delete the
339 whole tree from the cache. i.e. 'powerdns.com$' will remove all
340 cached entries under and including the powerdns.com name.
341 Note: this command also wipes the negative cache.
343 Warning: Don't just wipe "www.somedomain.com", its NS records or
345 CNAME target may still be undesired, so wipe "somedomain.com" as
346 well.
347 wipe-cache-typed qtype DOMAIN [DOMAIN] [...]
349 Same as wipe-cache, but only wipe records of type qtype.
350
352 pdns_recursor(1)
353
355 PowerDNS.COM BV
356
358 2001-2019, PowerDNS.COM BV
359 Dec 11, 2020 REC_CONTROL(1)