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
43 instead.
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. Set to 0 for infinite.
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
148 answer 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.
202 quit-nicely
204 Request nice shutdown of the recursor.
205 reload-acls
207 Reloads ACLs.
208 reload-lua-script [FILENAME]
210 (Re)loads Lua script FILENAME. If FILENAME is empty, attempt to
211 reload the currently loaded script. This replaces the script
212 currently loaded.
213 reload-lua-config [FILENAME]
215 (Re)loads Lua configuration FILENAME. If FILENAME is empty,
216 attempt to reload the currently loaded file. Note that FILENAME
217 will be fully executed, any settings changed at runtime that are
218 not modified in this file, will still be active. Reloading RPZ,
219 especially by AXFR, can take some time; during which the recur‐
220 sor will not answer questions.
221 reload-zones
223 Reload authoritative and forward zones. Retains current configu‐
224 ration in case of errors.
225 set-carbon-server CARBON SERVER [CARBON OURNAME]
227 Set the carbon-server setting to CARBON SERVER. If CARBON OUR‐
228 NAME is not empty, also set the carbon-ourname setting to CARBON
229 OURNAME.
230 set-dnssec-log-bogus SETTING
232 Set dnssec-log-bogus setting to SETTING. Set to 'on' or 'yes' to
233 log DNSSEC validation failures and to 'no' or 'off' to disable
234 logging these failures.
235 set-ecs-minimum-ttl NUM
237 Set ecs-minimum-ttl-override to NUM.
238 set-max-cache-entries NUM
240 Change the maximum number of entries in the DNS cache. If
241 reduced, the cache size will start shrinking to this number as
242 part of the normal cache purging process, which might take a
243 while.
244 set-max-packetcache-entries NUM
246 Change the maximum number of entries in the packet cache. If
247 reduced, the cache size will start shrinking to this number as
248 part of the normal cache purging process, which might take a
249 while.
250 set-minimum-ttl NUM
252 Set minimum-ttl-override to NUM.
253 top-queries
255 Shows the top-20 queries. Statistics are over the last
256 'stats-ringbuffer-entries' queries.
257 top-pub-queries
259 Shows the top-20 queries grouped by public suffix list. Statis‐
260 tics are over the last 'stats-ringbuffer-entries' queries.
261 top-largeanswer-remotes
263 Shows the top-20 remote hosts causing large answers. Statistics
264 are over the last 'stats-ringbuffer-entries' queries.
265 top-remotes
267 Shows the top-20 most active remote hosts. Statistics are over
268 the last 'stats-ringbuffer-entries' queries.
269 top-servfail-queries
271 Shows the top-20 queries causing servfail responses. Statistics
272 are over the last 'stats-ringbuffer-entries' queries.
273 top-bogus-queries
275 Shows the top-20 queries causing bogus responses. Statistics are
276 over the last 'stats-ringbuffer-entries' queries.
277 top-pub-servfail-queries
279 Shows the top-20 queries causing servfail responses grouped by
280 public suffix list. Statistics are over the last 'stats-ring‐
281 buffer-entries' queries.
282 top-pub-bogus-queries
284 Shows the top-20 queries causing bogus responses grouped by pub‐
285 lic suffix list. Statistics are over the last 'stats-ring‐
286 buffer-entries' queries.
287 top-servfail-remotes
289 Shows the top-20 most active remote hosts causing servfail
290 responses. Statistics are over the last 'stats-ring‐
291 buffer-entries' queries.
292 top-bogus-remotes
294 Shows the top-20 most active remote hosts causing bogus
295 responses. Statistics are over the last 'stats-ring‐
296 buffer-entries' queries.
297 top-timeouts
299 Shows the top-20 most active downstream timeout destinations.
300 Statistics are over the last 'stats-ringbuffer-entries' queries.
301 trace-regex REGEX
303 Emit resolution trace for matching queries. Empty regex to dis‐
304 able trace.
305 Queries matching this regular expression will generate volumi‐
307 nous tracing output. Be aware that matches from the packet cache
308 will still not generate tracing. To unset the regex, pass
309 trace-regex without a new regex.
310 The regular expression is matched against domain queries termi‐
312 nated with a '.'. For example the regex 'powerdns.com$' will not
313 match a query for 'www.powerdns.com', since the attempted match
314 will be with 'www.powerdns.com.'.
315 In addition, since this is a regular expression, to exclusively
317 match queries for 'www.powerdns.com', one should escape the
318 dots: '^www.powerdns.com.$'.
319 Multiple matches can be chained with the '|' operator. For exam‐
321 ple, to match all queries for Dutch (.nl) and German (.de)
322 domain names, use: '.nl.$|.de.$'.
323 unload-lua-script
325 Unloads Lua script if one was loaded.
326 version
328 Report running version.
329 wipe-cache DOMAIN [DOMAIN] [...]
331 Wipe entries for DOMAIN (exact name match) from the cache. This
332 is useful if, for example, an important server has a new IP
333 address, but the TTL has not yet expired. Multiple domain names
334 can be passed. DOMAIN can be suffixed with a '$'. to delete the
335 whole tree from the cache. i.e. 'powerdns.com$' will remove all
336 cached entries under and including the powerdns.com name.
337 Note: this command also wipes the negative cache.
339 Warning: Don't just wipe "www.somedomain.com", its NS records or
341 CNAME target may still be undesired, so wipe "somedomain.com" as
342 well.
343
345 pdns_recursor(1)
346
348 PowerDNS.COM BV
349
351 2001-2019, PowerDNS.COM BV
352 Nov 24, 2020 REC_CONTROL(1)