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 ping Check if server is alive.
198 quit Request shutdown of the recursor, exiting the process while let‐
200 ting the OS clean up resources.
201 quit-nicely
203 Request nice shutdown of the recursor. This method allows all
204 threads to finish their current work and releases resources be‐
205 fore exiting. This is the preferred method to stop the recursor.
206 reload-acls
208 Reloads ACLs.
209 reload-lua-script [FILENAME]
211 (Re)loads Lua script FILENAME. If FILENAME is empty, attempt to
212 reload the currently loaded script. This replaces the script
213 currently loaded.
214 reload-lua-config [FILENAME]
216 (Re)loads Lua configuration FILENAME. If FILENAME is empty, at‐
217 tempt to reload the currently loaded file. Note that FILENAME
218 will be fully executed, any settings changed at runtime that are
219 not modified in this file, will still be active. The effects of
220 reloading do not always take place immediately, as some subsys‐
221 tems reload and replace configuration in an asynchronous way.
222 reload-zones
224 Reload authoritative and forward zones. Retains current configu‐
225 ration in case of errors.
226 set-carbon-server CARBON SERVER [CARBON OURNAME]
228 Set the carbon-server setting to CARBON SERVER. If CARBON OUR‐
229 NAME is not empty, also set the carbon-ourname setting to CARBON
230 OURNAME.
231 set-dnssec-log-bogus SETTING
233 Set dnssec-log-bogus setting to SETTING. Set to 'on' or 'yes' to
234 log DNSSEC validation failures and to 'no' or 'off' to disable
235 logging these failures.
236 set-ecs-minimum-ttl NUM
238 Set ecs-minimum-ttl-override to NUM.
239 set-max-cache-entries NUM
241 Change the maximum number of entries in the DNS cache. If re‐
242 duced, the cache size will start shrinking to this number as
243 part of the normal cache purging process, which might take a
244 while.
245 set-max-packetcache-entries NUM
247 Change the maximum number of entries in the packet cache. If
248 reduced, the cache size will start shrinking to this number as
249 part of the normal cache purging process, which might take a
250 while.
251 set-minimum-ttl NUM
253 Set minimum-ttl-override to NUM.
254 set-event-trace-enabled NUM
256 Set logging of event trace messages, 0 = disabled, 1 = protobuf,
257 2 = log file, 3 = both.
258 top-queries
260 Shows the top-20 queries. Statistics are over the last
261 'stats-ringbuffer-entries' queries.
262 top-pub-queries
264 Shows the top-20 queries grouped by public suffix list. Statis‐
265 tics are over the last 'stats-ringbuffer-entries' queries.
266 top-largeanswer-remotes
268 Shows the top-20 remote hosts causing large answers. Statistics
269 are over the last 'stats-ringbuffer-entries' queries.
270 top-remotes
272 Shows the top-20 most active remote hosts. Statistics are over
273 the last 'stats-ringbuffer-entries' queries.
274 top-servfail-queries
276 Shows the top-20 queries causing servfail responses. Statistics
277 are over the last 'stats-ringbuffer-entries' queries.
278 top-bogus-queries
280 Shows the top-20 queries causing bogus responses. Statistics are
281 over the last 'stats-ringbuffer-entries' queries.
282 top-pub-servfail-queries
284 Shows the top-20 queries causing servfail responses grouped by
285 public suffix list. Statistics are over the last 'stats-ring‐
286 buffer-entries' queries.
287 top-pub-bogus-queries
289 Shows the top-20 queries causing bogus responses grouped by pub‐
290 lic suffix list. Statistics are over the last 'stats-ring‐
291 buffer-entries' queries.
292 top-servfail-remotes
294 Shows the top-20 most active remote hosts causing servfail re‐
295 sponses. Statistics are over the last 'stats-ringbuffer-en‐
296 tries' queries.
297 top-bogus-remotes
299 Shows the top-20 most active remote hosts causing bogus re‐
300 sponses. Statistics are over the last 'stats-ringbuffer-en‐
301 tries' queries.
302 top-timeouts
304 Shows the top-20 most active downstream timeout destinations.
305 Statistics are over the last 'stats-ringbuffer-entries' queries.
306 trace-regex REGEX
308 Emit resolution trace for matching queries. Empty regex to dis‐
309 able trace.
310 Queries matching this regular expression will generate volumi‐
312 nous tracing output. Be aware that matches from the packet cache
313 will still not generate tracing. To unset the regex, pass
314 trace-regex without a new regex.
315 The regular expression is matched against domain queries termi‐
317 nated with a dot. For example the regex 'powerdns.com$' will not
318 match a query for 'www.powerdns.com', since the attempted match
319 will be with 'www.powerdns.com.'.
320 In addition, since this is a regular expression, to exclusively
322 match queries for 'www.powerdns.com', one should escape the
323 dots: '^www\.powerdns\.com\.$'. Note that the single quotes
324 prevent further interpretation of the backslashes by the shell.
325 Multiple matches can be chained with the | operator. For exam‐
327 ple, to match all queries for Dutch (.nl) and German (.de) do‐
328 main names, use: '\.nl\.$|\.de\.$'.
329 unload-lua-script
331 Unloads Lua script if one was loaded.
332 version
334 Report running version.
335 wipe-cache DOMAIN [DOMAIN] [...]
337 Wipe entries for DOMAIN (exact name match) from the cache. This
338 is useful if, for example, an important server has a new IP ad‐
339 dress, but the TTL has not yet expired. Multiple domain names
340 can be passed. DOMAIN can be suffixed with a '$'. to delete the
341 whole tree from the cache. i.e. 'powerdns.com$' will remove all
342 cached entries under and including the powerdns.com name.
343 Note: this command also wipes the negative cache.
345 Warning: Don't just wipe "www.somedomain.com", its NS records or
347 CNAME target may still be undesired, so wipe "somedomain.com" as
348 well.
349 wipe-cache-typed qtype DOMAIN [DOMAIN] [...]
351 Same as wipe-cache, but only wipe records of type qtype.
352
354 pdns_recursor(1) https://docs.powerdns.com/recursor
355
357 PowerDNS.COM BV
358
360 2001-2023, PowerDNS.COM BV
361 Mar 27, 2023 REC_CONTROL(1)