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-rpz ZONE_NAME /tmp/file
155 mv /proc/$(pidof pdns_recursor)/root/tmp/file /tmp/filename
156 get STATISTIC [STATISTIC]...
158 Retrieve a statistic. For items that can be queried, see ../met‐
159 rics
160 get-all
162 Retrieve all known statistics.
163 get-dont-throttle-names
165 Get the list of names that are not allowed to be throttled.
166 get-dont-throttle-netmasks
168 Get the list of netmasks that are not allowed to be throttled.
169 get-ntas
171 Get a list of the currently configured Negative Trust Anchors.
172 get-tas
174 Get a list of the currently configured Trust Anchors.
175 get-parameter KEY [KEY]...
177 Retrieves the specified configuration parameter(s).
178 get-qtypelist
180 Retrieves QType statistics. Queries from cache aren't being
181 counted yet.
182 help Shows a list of supported commands understood by the running
184 pdns_recursor
185 ping Check if server is alive.
187 quit Request shutdown of the recursor.
189 quit-nicely
191 Request nice shutdown of the recursor.
192 reload-acls
194 Reloads ACLs.
195 reload-lua-script [FILENAME]
197 (Re)loads Lua script FILENAME. If FILENAME is empty, attempt to
198 reload the currently loaded script. This replaces the script
199 currently loaded.
200 reload-lua-config [FILENAME]
202 (Re)loads Lua configuration FILENAME. If FILENAME is empty,
203 attempt to reload the currently loaded file. Note that FILENAME
204 will be fully executed, any settings changed at runtime that are
205 not modified in this file, will still be active. Reloading RPZ,
206 especially by AXFR, can take some time; during which the recur‐
207 sor will not answer questions.
208 reload-zones
210 Reload authoritative and forward zones. Retains current configu‐
211 ration in case of errors.
212 set-carbon-server CARBON SERVER [CARBON OURNAME]
214 Set the carbon-server setting to CARBON SERVER. If CARBON OUR‐
215 NAME is not empty, also set the carbon-ourname setting to CARBON
216 OURNAME.
217 set-dnssec-log-bogus SETTING
219 Set dnssec-log-bogus setting to SETTING. Set to 'on' or 'yes' to
220 log DNSSEC validation failures and to 'no' or 'off' to disable
221 logging these failures.
222 set-ecs-minimum-ttl NUM
224 Set ecs-minimum-ttl-override to NUM.
225 set-max-cache-entries NUM
227 Change the maximum number of entries in the DNS cache. If
228 reduced, the cache size will start shrinking to this number as
229 part of the normal cache purging process, which might take a
230 while.
231 set-max-packetcache-entries NUM
233 Change the maximum number of entries in the packet cache. If
234 reduced, the cache size will start shrinking to this number as
235 part of the normal cache purging process, which might take a
236 while.
237 set-minimum-ttl NUM
239 Set minimum-ttl-override to NUM.
240 top-queries
242 Shows the top-20 queries. Statistics are over the last
243 'stats-ringbuffer-entries' queries.
244 top-pub-queries
246 Shows the top-20 queries grouped by public suffix list. Statis‐
247 tics are over the last 'stats-ringbuffer-entries' queries.
248 top-largeanswer-remotes
250 Shows the top-20 remote hosts causing large answers. Statistics
251 are over the last 'stats-ringbuffer-entries' queries.
252 top-remotes
254 Shows the top-20 most active remote hosts. Statistics are over
255 the last 'stats-ringbuffer-entries' queries.
256 top-servfail-queries
258 Shows the top-20 queries causing servfail responses. Statistics
259 are over the last 'stats-ringbuffer-entries' queries.
260 top-bogus-queries
262 Shows the top-20 queries causing bogus responses. Statistics are
263 over the last 'stats-ringbuffer-entries' queries.
264 top-pub-servfail-queries
266 Shows the top-20 queries causing servfail responses grouped by
267 public suffix list. Statistics are over the last 'stats-ring‐
268 buffer-entries' queries.
269 top-pub-bogus-queries
271 Shows the top-20 queries causing bogus responses grouped by pub‐
272 lic suffix list. Statistics are over the last 'stats-ring‐
273 buffer-entries' queries.
274 top-servfail-remotes
276 Shows the top-20 most active remote hosts causing servfail
277 responses. Statistics are over the last 'stats-ring‐
278 buffer-entries' queries.
279 top-bogus-remotes
281 Shows the top-20 most active remote hosts causing bogus
282 responses. Statistics are over the last 'stats-ring‐
283 buffer-entries' queries.
284 top-timeouts
286 Shows the top-20 most active downstream timeout destinations.
287 Statistics are over the last 'stats-ringbuffer-entries' queries.
288 trace-regex REGEX
290 Emit resolution trace for matching queries. Empty regex to dis‐
291 able trace.
292 Queries matching this regular expression will generate volumi‐
294 nous tracing output. Be aware that matches from the packet cache
295 will still not generate tracing. To unset the regex, pass
296 trace-regex without a new regex.
297 The regular expression is matched against domain queries termi‐
299 nated with a '.'. For example the regex 'powerdns.com$' will not
300 match a query for 'www.powerdns.com', since the attempted match
301 will be with 'www.powerdns.com.'.
302 In addition, since this is a regular expression, to exclusively
304 match queries for 'www.powerdns.com', one should escape the
305 dots: '^www.powerdns.com.$'.
306 Multiple matches can be chained with the '|' operator. For exam‐
308 ple, to match all queries for Dutch (.nl) and German (.de)
309 domain names, use: '.nl.$|.de.$'.
310 unload-lua-script
312 Unloads Lua script if one was loaded.
313 version
315 Report running version.
316 wipe-cache DOMAIN [DOMAIN] [...]
318 Wipe entries for DOMAIN (exact name match) from the cache. This
319 is useful if, for example, an important server has a new IP
320 address, but the TTL has not yet expired. Multiple domain names
321 can be passed. DOMAIN can be suffixed with a '$'. to delete the
322 whole tree from the cache. i.e. 'powerdns.com$' will remove all
323 cached entries under and including the powerdns.com name.
324 Note: this command also wipes the negative cache.
326 Warning: Don't just wipe "www.somedomain.com", its NS records or
328 CNAME target may still be undesired, so wipe "somedomain.com" as
329 well.
330
332 pdns_recursor(1)
333
335 PowerDNS.COM BV
336
338 2001-2019, PowerDNS.COM BV
3394.1 Jul 15, 2019 REC_CONTROL(1)