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 NOTE:
33 Before version 4.5.0, for each command that writes to a file,
34 pdns_recursor would open the file to write to. Starting with 4.5.0,
35 the files are opened by the rec_control command itself using the
36 credentials and the current working directory of the user running
37 rec_control. A single minus - can be used as a filename to write
38 the data to the standard output stream.
39
41 --help provide this helpful message.
42 --config-dir=<path>
44 Directory where the recursor.conf lives.
45 --config-name=<name>
47 Name of the virtual configuration.
48 --socket-dir=<path>
50 Where the controlsocket will live, please use --config-dir in‐
51 stead.
52 --socket-pid=<pid>
54 When running in SMP mode, pid of pdns_recursor to control.
55 --timeout=<num>
57 Number of seconds to wait for the remote PowerDNS Recursor to
58 respond.
59
61 add-dont-throttle-names NAME [NAME...]
62 Add names for nameserver domains that may not be throttled.
63 add-dont-throttle-netmasks NETMASK [NETMASK...]
65 Add netmasks for nameservers that may not be throttled.
66 add-nta DOMAIN [REASON]
68 Add a Negative Trust Anchor for DOMAIN, suffixed optionally with
69 REASON.
70 add-ta DOMAIN DSRECORD
72 Add a Trust Anchor for DOMAIN with DS record data DSRECORD. This
73 adds the new Trust Anchor to the existing set of Trust Anchors
74 for DOMAIN.
75 current-queries
77 Shows the currently active queries.
78 clear-dont-throttle-names NAME [NAME...]
80 Remove names that are not allowed to be throttled. If NAME is
81 '*', remove all
82 clear-dont-throttle-netmasks NETMASK [NETMASK...]
84 Remove netmasks that are not allowed to be throttled. If NETMASK
85 is '*', remove all
86 clear-nta DOMAIN...
88 Remove Negative Trust Anchor for one or more DOMAINs. Set domain
89 to '*' to remove all NTA's.
90 clear-ta [DOMAIN]...
92 Remove Trust Anchor for one or more DOMAINs. Note that removing
93 the root trust anchor is not possible.
94 dump-cache FILENAME
96 Dumps the entire cache to FILENAME. This file should not exist
97 already, PowerDNS will refuse to overwrite it. While dumping,
98 the recursor might not answer questions.
99 Typical PowerDNS Recursors run multiple threads, therefore
101 you'll see duplicate, different entries for the same domains.
102 The negative cache is also dumped to the same file. The
103 per-thread positive and negative cache dumps are separated with
104 an appropriate comment.
105 dump-dot-probe-map FILENAME
107 Dump the contents of the DoT probe map to the FILENAME men‐
108 tioned.
109 dump-edns FILENAME
111 Dumps the EDNS status to the filename mentioned. This file
112 should not exist already, PowerDNS will refuse to overwrite it.
113 While dumping, the recursor will not answer questions.
114 dump-failedservers FILENAME
116 Dump the contents of the failed server map to the FILENAME men‐
117 tioned. This file should not exist already, PowerDNS will
118 refuse to overwrite it otherwise. While dumping, the recursor
119 will not answer questions.
120 dump-non-resolving FILENAME
122 Dump the contents of the map of nameserver names that did not
123 resolve to an address. This file should not exist already, Pow‐
124 erDNS will refuse to overwrite it otherwise. While dumping, the
125 recursor will not answer questions.
126 dump-nsspeeds FILENAME
128 Dumps the nameserver speed statistics to the FILENAME mentioned.
129 This file should not exist already, PowerDNS will refuse to
130 overwrite it. While dumping, the recursor will not answer ques‐
131 tions. Statistics are kept per thread, and the dumps end up in
132 the same file.
133 dump-rpz ZONE NAME FILE NAME
135 Dumps the content of the RPZ zone named ZONE NAME to the FILE‐
136 NAME mentioned. This file should not exist already, PowerDNS
137 will refuse to overwrite it otherwise. While dumping, the recur‐
138 sor will not answer questions.
139 dump-saved-parent-ns-sets FILE NAME
141 Dump the entries of the map containing saved parent NS sets that
142 were successfully used in resolving. The total number of en‐
143 tries is also printed in the header. An entry is saved if the
144 recursor sees that the parent set includes names not in the
145 child set. This is an indication of a misconfigured domain.
146 dump-throttlemap FILENAME
148 Dump the contents of the throttle map to the FILENAME mentioned.
149 This file should not exist already, PowerDNS will refuse to
150 overwrite it otherwise. While dumping, the recursor will not an‐
151 swer questions.
152 get STATISTIC [STATISTIC]...
154 Retrieve a statistic. For items that can be queried, see ../met‐
155 rics
156 get-all
158 Retrieve all known statistics.
159 get-dont-throttle-names
161 Get the list of names that are not allowed to be throttled.
162 get-dont-throttle-netmasks
164 Get the list of netmasks that are not allowed to be throttled.
165 get-ntas
167 Get a list of the currently configured Negative Trust Anchors.
168 get-tas
170 Get a list of the currently configured Trust Anchors.
171 get-parameter KEY [KEY]...
173 Retrieves the specified configuration parameter(s).
174 get-qtypelist
176 Retrieves QType statistics. Queries from cache aren't being
177 counted yet.
178 hash-password [WORK-FACTOR]
180 Asks for a password then returns the hashed and salted version,
181 to use as a webserver password or API key. This command does not
182 contact the recursor but does the hashing inside rec_control.
183 An optional scrypt work factor can be specified, in power of
184 two. The default is 1024.
185 help Shows a list of supported commands understood by the running
187 pdns_recursor
188 ping Check if server is alive.
190 quit Request shutdown of the recursor, exiting the process while let‐
192 ting the OS clean up resources.
193 quit-nicely
195 Request nice shutdown of the recursor. This method allows all
196 threads to finish their current work and releases resources be‐
197 fore exiting. This is the preferred method to stop the recursor.
198 reload-acls
200 Reloads ACLs.
201 reload-lua-script [FILENAME]
203 (Re)loads Lua script FILENAME. If FILENAME is empty, attempt to
204 reload the currently loaded script. This replaces the script
205 currently loaded.
206 reload-lua-config [FILENAME]
208 (Re)loads Lua configuration FILENAME. If FILENAME is empty, at‐
209 tempt to reload the currently loaded file. Note that FILENAME
210 will be fully executed, any settings changed at runtime that are
211 not modified in this file, will still be active. Reloading RPZ,
212 especially by AXFR, can take some time; during which the recur‐
213 sor will not answer questions.
214 reload-zones
216 Reload authoritative and forward zones. Retains current configu‐
217 ration in case of errors.
218 set-carbon-server CARBON SERVER [CARBON OURNAME]
220 Set the carbon-server setting to CARBON SERVER. If CARBON OUR‐
221 NAME is not empty, also set the carbon-ourname setting to CARBON
222 OURNAME.
223 set-dnssec-log-bogus SETTING
225 Set dnssec-log-bogus setting to SETTING. Set to 'on' or 'yes' to
226 log DNSSEC validation failures and to 'no' or 'off' to disable
227 logging these failures.
228 set-ecs-minimum-ttl NUM
230 Set ecs-minimum-ttl-override to NUM.
231 set-max-cache-entries NUM
233 Change the maximum number of entries in the DNS cache. If re‐
234 duced, 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-max-packetcache-entries NUM
239 Change the maximum number of entries in the packet cache. If
240 reduced, the cache size will start shrinking to this number as
241 part of the normal cache purging process, which might take a
242 while.
243 set-minimum-ttl NUM
245 Set minimum-ttl-override to NUM.
246 set-event-trace-enabled NUM
248 Set logging of event trace messages, 0 = disabled, 1 = protobuf,
249 2 = log file, 3 = both.
250 top-queries
252 Shows the top-20 queries. Statistics are over the last
253 'stats-ringbuffer-entries' queries.
254 top-pub-queries
256 Shows the top-20 queries grouped by public suffix list. Statis‐
257 tics are over the last 'stats-ringbuffer-entries' queries.
258 top-largeanswer-remotes
260 Shows the top-20 remote hosts causing large answers. Statistics
261 are over the last 'stats-ringbuffer-entries' queries.
262 top-remotes
264 Shows the top-20 most active remote hosts. Statistics are over
265 the last 'stats-ringbuffer-entries' queries.
266 top-servfail-queries
268 Shows the top-20 queries causing servfail responses. Statistics
269 are over the last 'stats-ringbuffer-entries' queries.
270 top-bogus-queries
272 Shows the top-20 queries causing bogus responses. Statistics are
273 over the last 'stats-ringbuffer-entries' queries.
274 top-pub-servfail-queries
276 Shows the top-20 queries causing servfail responses grouped by
277 public suffix list. Statistics are over the last 'stats-ring‐
278 buffer-entries' queries.
279 top-pub-bogus-queries
281 Shows the top-20 queries causing bogus responses grouped by pub‐
282 lic suffix list. Statistics are over the last 'stats-ring‐
283 buffer-entries' queries.
284 top-servfail-remotes
286 Shows the top-20 most active remote hosts causing servfail re‐
287 sponses. Statistics are over the last 'stats-ringbuffer-en‐
288 tries' queries.
289 top-bogus-remotes
291 Shows the top-20 most active remote hosts causing bogus re‐
292 sponses. Statistics are over the last 'stats-ringbuffer-en‐
293 tries' queries.
294 top-timeouts
296 Shows the top-20 most active downstream timeout destinations.
297 Statistics are over the last 'stats-ringbuffer-entries' queries.
298 trace-regex REGEX
300 Emit resolution trace for matching queries. Empty regex to dis‐
301 able trace.
302 Queries matching this regular expression will generate volumi‐
304 nous tracing output. Be aware that matches from the packet cache
305 will still not generate tracing. To unset the regex, pass
306 trace-regex without a new regex.
307 The regular expression is matched against domain queries termi‐
309 nated with a dot. For example the regex 'powerdns.com$' will not
310 match a query for 'www.powerdns.com', since the attempted match
311 will be with 'www.powerdns.com.'.
312 In addition, since this is a regular expression, to exclusively
314 match queries for 'www.powerdns.com', one should escape the
315 dots: '^www\.powerdns\.com\.$'. Note that the single quotes
316 prevent further interpretation of the backslashes by the shell.
317 Multiple matches can be chained with the | operator. For exam‐
319 ple, to match all queries for Dutch (.nl) and German (.de) do‐
320 main names, use: '\.nl\.$|\.de\.$'.
321 unload-lua-script
323 Unloads Lua script if one was loaded.
324 version
326 Report running version.
327 wipe-cache DOMAIN [DOMAIN] [...]
329 Wipe entries for DOMAIN (exact name match) from the cache. This
330 is useful if, for example, an important server has a new IP ad‐
331 dress, but the TTL has not yet expired. Multiple domain names
332 can be passed. DOMAIN can be suffixed with a '$'. to delete the
333 whole tree from the cache. i.e. 'powerdns.com$' will remove all
334 cached entries under and including the powerdns.com name.
335 Note: this command also wipes the negative cache.
337 Warning: Don't just wipe "www.somedomain.com", its NS records or
339 CNAME target may still be undesired, so wipe "somedomain.com" as
340 well.
341 wipe-cache-typed qtype DOMAIN [DOMAIN] [...]
343 Same as wipe-cache, but only wipe records of type qtype.
344
346 pdns_recursor(1)
347
349 PowerDNS.COM BV
350
352 2001-2022, PowerDNS.COM BV
353 Jul 07, 2022 REC_CONTROL(1)