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-edns FILENAME
107 Dumps the EDNS status to the filename mentioned. This file
108 should not exist already, PowerDNS will refuse to overwrite it.
109 While dumping, the recursor will not answer questions.
110 dump-failedservers FILENAME
112 Dump the contents of the failed server map to the FILENAME men‐
113 tioned. This file should not exist already, PowerDNS will
114 refuse to overwrite it otherwise. While dumping, the recursor
115 will not answer questions.
116 dump-non-resolving FILENAME
118 Dump the contents of the map of nameserver names that did not
119 resolve to an address. This file should not exist already, Pow‐
120 erDNS will refuse to overwrite it otherwise. While dumping, the
121 recursor will not answer questions.
122 dump-nsspeeds FILENAME
124 Dumps the nameserver speed statistics to the FILENAME mentioned.
125 This file should not exist already, PowerDNS will refuse to
126 overwrite it. While dumping, the recursor will not answer ques‐
127 tions. Statistics are kept per thread, and the dumps end up in
128 the same file.
129 dump-rpz ZONE NAME FILE NAME
131 Dumps the content of the RPZ zone named ZONE NAME to the FILE‐
132 NAME mentioned. This file should not exist already, PowerDNS
133 will refuse to overwrite it otherwise. While dumping, the recur‐
134 sor will not answer questions.
135 dump-throttlemap FILENAME
137 Dump the contents of the throttle map to the FILENAME mentioned.
138 This file should not exist already, PowerDNS will refuse to
139 overwrite it otherwise. While dumping, the recursor will not an‐
140 swer questions.
141 get STATISTIC [STATISTIC]...
143 Retrieve a statistic. For items that can be queried, see ../met‐
144 rics
145 get-all
147 Retrieve all known statistics.
148 get-dont-throttle-names
150 Get the list of names that are not allowed to be throttled.
151 get-dont-throttle-netmasks
153 Get the list of netmasks that are not allowed to be throttled.
154 get-ntas
156 Get a list of the currently configured Negative Trust Anchors.
157 get-tas
159 Get a list of the currently configured Trust Anchors.
160 get-parameter KEY [KEY]...
162 Retrieves the specified configuration parameter(s).
163 get-qtypelist
165 Retrieves QType statistics. Queries from cache aren't being
166 counted yet.
167 hash-password [WORK-FACTOR]
169 Asks for a password then returns the hashed and salted version,
170 to use as a webserver password or API key. This command does not
171 contact the recursor but does the hashing inside rec_control.
172 An optional scrypt work factor can be specified, in power of
173 two. The default is 1024.
174 help Shows a list of supported commands understood by the running
176 pdns_recursor
177 ping Check if server is alive.
179 quit Request shutdown of the recursor, exiting the process while let‐
181 ting the OS clean up resources.
182 quit-nicely
184 Request nice shutdown of the recursor. This method allows all
185 threads to finish their current work and releases resources be‐
186 fore exiting. This is the preferred method to stop the recursor.
187 reload-acls
189 Reloads ACLs.
190 reload-lua-script [FILENAME]
192 (Re)loads Lua script FILENAME. If FILENAME is empty, attempt to
193 reload the currently loaded script. This replaces the script
194 currently loaded.
195 reload-lua-config [FILENAME]
197 (Re)loads Lua configuration FILENAME. If FILENAME is empty, at‐
198 tempt to reload the currently loaded file. Note that FILENAME
199 will be fully executed, any settings changed at runtime that are
200 not modified in this file, will still be active. Reloading RPZ,
201 especially by AXFR, can take some time; during which the recur‐
202 sor will not answer questions.
203 reload-zones
205 Reload authoritative and forward zones. Retains current configu‐
206 ration in case of errors.
207 set-carbon-server CARBON SERVER [CARBON OURNAME]
209 Set the carbon-server setting to CARBON SERVER. If CARBON OUR‐
210 NAME is not empty, also set the carbon-ourname setting to CARBON
211 OURNAME.
212 set-dnssec-log-bogus SETTING
214 Set dnssec-log-bogus setting to SETTING. Set to 'on' or 'yes' to
215 log DNSSEC validation failures and to 'no' or 'off' to disable
216 logging these failures.
217 set-ecs-minimum-ttl NUM
219 Set ecs-minimum-ttl-override to NUM.
220 set-max-cache-entries NUM
222 Change the maximum number of entries in the DNS cache. If re‐
223 duced, the cache size will start shrinking to this number as
224 part of the normal cache purging process, which might take a
225 while.
226 set-max-packetcache-entries NUM
228 Change the maximum number of entries in the packet cache. If
229 reduced, the cache size will start shrinking to this number as
230 part of the normal cache purging process, which might take a
231 while.
232 set-minimum-ttl NUM
234 Set minimum-ttl-override to NUM.
235 set-event-trace-enabled NUM
237 Set logging of event trace messages, 0 = disabled, 1 = protobuf,
238 2 = log file, 3 = both.
239 top-queries
241 Shows the top-20 queries. Statistics are over the last
242 'stats-ringbuffer-entries' queries.
243 top-pub-queries
245 Shows the top-20 queries grouped by public suffix list. Statis‐
246 tics are over the last 'stats-ringbuffer-entries' queries.
247 top-largeanswer-remotes
249 Shows the top-20 remote hosts causing large answers. Statistics
250 are over the last 'stats-ringbuffer-entries' queries.
251 top-remotes
253 Shows the top-20 most active remote hosts. Statistics are over
254 the last 'stats-ringbuffer-entries' queries.
255 top-servfail-queries
257 Shows the top-20 queries causing servfail responses. Statistics
258 are over the last 'stats-ringbuffer-entries' queries.
259 top-bogus-queries
261 Shows the top-20 queries causing bogus responses. Statistics are
262 over the last 'stats-ringbuffer-entries' queries.
263 top-pub-servfail-queries
265 Shows the top-20 queries causing servfail responses grouped by
266 public suffix list. Statistics are over the last 'stats-ring‐
267 buffer-entries' queries.
268 top-pub-bogus-queries
270 Shows the top-20 queries causing bogus responses grouped by pub‐
271 lic suffix list. Statistics are over the last 'stats-ring‐
272 buffer-entries' queries.
273 top-servfail-remotes
275 Shows the top-20 most active remote hosts causing servfail re‐
276 sponses. Statistics are over the last 'stats-ringbuffer-en‐
277 tries' queries.
278 top-bogus-remotes
280 Shows the top-20 most active remote hosts causing bogus re‐
281 sponses. Statistics are over the last 'stats-ringbuffer-en‐
282 tries' queries.
283 top-timeouts
285 Shows the top-20 most active downstream timeout destinations.
286 Statistics are over the last 'stats-ringbuffer-entries' queries.
287 trace-regex REGEX
289 Emit resolution trace for matching queries. Empty regex to dis‐
290 able trace.
291 Queries matching this regular expression will generate volumi‐
293 nous tracing output. Be aware that matches from the packet cache
294 will still not generate tracing. To unset the regex, pass
295 trace-regex without a new regex.
296 The regular expression is matched against domain queries termi‐
298 nated with a dot. For example the regex 'powerdns.com$' will not
299 match a query for 'www.powerdns.com', since the attempted match
300 will be with 'www.powerdns.com.'.
301 In addition, since this is a regular expression, to exclusively
303 match queries for 'www.powerdns.com', one should escape the
304 dots: '^www\.powerdns\.com\.$'. Note that the single quotes
305 prevent further interpretation of the backslashes by the shell.
306 Multiple matches can be chained with the | operator. For exam‐
308 ple, to match all queries for Dutch (.nl) and German (.de) do‐
309 main 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 ad‐
320 dress, 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 wipe-cache-typed qtype DOMAIN [DOMAIN] [...]
332 Same as wipe-cache, but only wipe records of type qtype.
333
335 pdns_recursor(1)
336
338 PowerDNS.COM BV
339
341 2001-2022, PowerDNS.COM BV
342 Mar 30, 2022 REC_CONTROL(1)