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. For details on how RPZ are named
139 see
140 https://docs.powerdns.com/recursor/lua-config/rpz.html#policyname.
141 dump-saved-parent-ns-sets FILE NAME
143 Dump the entries of the map containing saved parent NS sets that
144 were successfully used in resolving. The total number of en‐
145 tries is also printed in the header. An entry is saved if the
146 recursor sees that the parent set includes names not in the
147 child set. This is an indication of a misconfigured domain.
148 dump-throttlemap FILENAME
150 Dump the contents of the throttle map to the FILENAME mentioned.
151 This file should not exist already, PowerDNS will refuse to
152 overwrite it otherwise. While dumping, the recursor will not an‐
153 swer questions.
154 get STATISTIC [STATISTIC]...
156 Retrieve a statistic. For items that can be queried, see
157 https://docs.powerdns.com/recursor/metrics.html.
158 get-all
160 Retrieve all known statistics.
161 get-dont-throttle-names
163 Get the list of names that are not allowed to be throttled.
164 get-dont-throttle-netmasks
166 Get the list of netmasks that are not allowed to be throttled.
167 get-ntas
169 Get a list of the currently configured Negative Trust Anchors.
170 get-tas
172 Get a list of the currently configured Trust Anchors.
173 get-parameter KEY [KEY]...
175 Retrieves the specified configuration parameter(s).
176 get-proxymapping-stats
178 Get the list of proxy-mapped subnets and associated counters.
179 get-qtypelist
181 Retrieves QType statistics. Queries from cache aren't being
182 counted yet.
183 get-remotelogger-stats
185 Retrieves the remote logger statistics, per type and address.
186 hash-password [WORK-FACTOR]
188 Asks for a password then returns the hashed and salted version,
189 to use as a webserver password or API key. This command does not
190 contact the recursor but does the hashing inside rec_control.
191 An optional scrypt work factor can be specified, in power of
192 two. The default is 1024.
193 help Shows a list of supported commands understood by the running
195 pdns_recursor
196 list-dnssec-algos
198 List supported (and potentially disabled) DNSSEC algorithms.
199 ping Check if server is alive.
201 quit Request shutdown of the recursor, exiting the process while let‐
203 ting the OS clean up resources.
204 quit-nicely
206 Request nice shutdown of the recursor. This method allows all
207 threads to finish their current work and releases resources be‐
208 fore exiting. This is the preferred method to stop the recursor.
209 reload-acls
211 Reloads ACLs.
212 reload-lua-script [FILENAME]
214 (Re)loads Lua script FILENAME. If FILENAME is empty, attempt to
215 reload the currently loaded script. This replaces the script
216 currently loaded.
217 reload-lua-config [FILENAME]
219 (Re)loads Lua configuration FILENAME. If FILENAME is empty, at‐
220 tempt to reload the currently loaded file. Note that FILENAME
221 will be fully executed, any settings changed at runtime that are
222 not modified in this file, will still be active. The effects of
223 reloading do not always take place immediately, as some subsys‐
224 tems reload and replace configuration in an asynchronous way.
225 reload-zones
227 Reload authoritative and forward zones. Retains current configu‐
228 ration in case of errors.
229 set-carbon-server CARBON SERVER [CARBON OURNAME]
231 Set the carbon-server setting to CARBON SERVER. If CARBON OUR‐
232 NAME is not empty, also set the carbon-ourname setting to CARBON
233 OURNAME.
234 set-dnssec-log-bogus SETTING
236 Set dnssec-log-bogus setting to SETTING. Set to 'on' or 'yes' to
237 log DNSSEC validation failures and to 'no' or 'off' to disable
238 logging these failures.
239 set-ecs-minimum-ttl NUM
241 Set ecs-minimum-ttl-override to NUM.
242 set-max-cache-entries NUM
244 Change the maximum number of entries in the DNS cache. If re‐
245 duced, the cache size will start shrinking to this number as
246 part of the normal cache purging process, which might take a
247 while.
248 set-max-packetcache-entries NUM
250 Change the maximum number of entries in the packet cache. If
251 reduced, the cache size will start shrinking to this number as
252 part of the normal cache purging process, which might take a
253 while.
254 set-minimum-ttl NUM
256 Set minimum-ttl-override to NUM.
257 set-event-trace-enabled NUM
259 Set logging of event trace messages, 0 = disabled, 1 = protobuf,
260 2 = log file, 3 = both.
261 top-queries
263 Shows the top-20 queries. Statistics are over the last
264 'stats-ringbuffer-entries' queries.
265 top-pub-queries
267 Shows the top-20 queries grouped by public suffix list. Statis‐
268 tics are over the last 'stats-ringbuffer-entries' queries.
269 top-largeanswer-remotes
271 Shows the top-20 remote hosts causing large answers. Statistics
272 are over the last 'stats-ringbuffer-entries' queries.
273 top-remotes
275 Shows the top-20 most active remote hosts. Statistics are over
276 the last 'stats-ringbuffer-entries' queries.
277 top-servfail-queries
279 Shows the top-20 queries causing servfail responses. Statistics
280 are over the last 'stats-ringbuffer-entries' queries.
281 top-bogus-queries
283 Shows the top-20 queries causing bogus responses. Statistics are
284 over the last 'stats-ringbuffer-entries' queries.
285 top-pub-servfail-queries
287 Shows the top-20 queries causing servfail responses grouped by
288 public suffix list. Statistics are over the last 'stats-ring‐
289 buffer-entries' queries.
290 top-pub-bogus-queries
292 Shows the top-20 queries causing bogus responses grouped by pub‐
293 lic suffix list. Statistics are over the last 'stats-ring‐
294 buffer-entries' queries.
295 top-servfail-remotes
297 Shows the top-20 most active remote hosts causing servfail re‐
298 sponses. Statistics are over the last 'stats-ringbuffer-en‐
299 tries' queries.
300 top-bogus-remotes
302 Shows the top-20 most active remote hosts causing bogus re‐
303 sponses. Statistics are over the last 'stats-ringbuffer-en‐
304 tries' queries.
305 top-timeouts
307 Shows the top-20 most active downstream timeout destinations.
308 Statistics are over the last 'stats-ringbuffer-entries' queries.
309 trace-regex REGEX FILE
311 Emit resolution trace for matching queries. No arguments dis‐
312 ables tracing. Before version 4.9.0, there was no FILE argu‐
313 ment, traces were always written to the log. Starting with ver‐
314 sion 4.9.0, trace information is written to the file specified,
315 which may be - for the standard out stream.
316 Queries matching this regular expression will generate volumi‐
318 nous tracing output. Be aware that matches from the packet cache
319 will still not generate tracing. To unset the regex, pass
320 trace-regex without a new regex.
321 The regular expression is matched against domain queries termi‐
323 nated with a dot. For example the regex 'powerdns.com$' will not
324 match a query for 'www.powerdns.com', since the attempted match
325 will be with 'www.powerdns.com.'.
326 In addition, since this is a regular expression, to exclusively
328 match queries for 'www.powerdns.com', one should escape the
329 dots: '^www\.powerdns\.com\.$'. Note that the single quotes
330 prevent further interpretation of the backslashes by the shell.
331 Multiple matches can be chained with the | operator. For exam‐
333 ple, to match all queries for Dutch (.nl) and German (.de) do‐
334 main names, use: '\.nl\.$|\.de\.$'.
335 unload-lua-script
337 Unloads Lua script if one was loaded.
338 version
340 Report running version.
341 wipe-cache DOMAIN [DOMAIN] [...]
343 Wipe entries for DOMAIN (exact name match) from the cache. This
344 is useful if, for example, an important server has a new IP ad‐
345 dress, but the TTL has not yet expired. Multiple domain names
346 can be passed. DOMAIN can be suffixed with a '$'. to delete the
347 whole tree from the cache. i.e. 'powerdns.com$' will remove all
348 cached entries under and including the powerdns.com name.
349 Note: this command also wipes the negative cache.
351 Warning: Don't just wipe "www.somedomain.com", its NS records or
353 CNAME target may still be undesired, so wipe "somedomain.com" as
354 well.
355 wipe-cache-typed qtype DOMAIN [DOMAIN] [...]
357 Same as wipe-cache, but only wipe records of type qtype.
358
360 pdns_recursor(1) https://docs.powerdns.com/recursor
361
363 PowerDNS.COM BV
364
366 2001-2023, PowerDNS.COM BV
367 Nov 07, 2023 REC_CONTROL(1)