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 help Shows a list of supported commands understood by the running
169 pdns_recursor
170 ping Check if server is alive.
172 quit Request shutdown of the recursor, exiting the process while let‐
174 ting the OS clean up resources.
175 quit-nicely
177 Request nice shutdown of the recursor. This method allows all
178 threads to finish their current work and releases resources be‐
179 fore exiting. This is the preferred method to stop the recursor.
180 reload-acls
182 Reloads ACLs.
183 reload-lua-script [FILENAME]
185 (Re)loads Lua script FILENAME. If FILENAME is empty, attempt to
186 reload the currently loaded script. This replaces the script
187 currently loaded.
188 reload-lua-config [FILENAME]
190 (Re)loads Lua configuration FILENAME. If FILENAME is empty, at‐
191 tempt to reload the currently loaded file. Note that FILENAME
192 will be fully executed, any settings changed at runtime that are
193 not modified in this file, will still be active. Reloading RPZ,
194 especially by AXFR, can take some time; during which the recur‐
195 sor will not answer questions.
196 reload-zones
198 Reload authoritative and forward zones. Retains current configu‐
199 ration in case of errors.
200 set-carbon-server CARBON SERVER [CARBON OURNAME]
202 Set the carbon-server setting to CARBON SERVER. If CARBON OUR‐
203 NAME is not empty, also set the carbon-ourname setting to CARBON
204 OURNAME.
205 set-dnssec-log-bogus SETTING
207 Set dnssec-log-bogus setting to SETTING. Set to 'on' or 'yes' to
208 log DNSSEC validation failures and to 'no' or 'off' to disable
209 logging these failures.
210 set-ecs-minimum-ttl NUM
212 Set ecs-minimum-ttl-override to NUM.
213 set-max-cache-entries NUM
215 Change the maximum number of entries in the DNS cache. If re‐
216 duced, the cache size will start shrinking to this number as
217 part of the normal cache purging process, which might take a
218 while.
219 set-max-packetcache-entries NUM
221 Change the maximum number of entries in the packet cache. If
222 reduced, the cache size will start shrinking to this number as
223 part of the normal cache purging process, which might take a
224 while.
225 set-minimum-ttl NUM
227 Set minimum-ttl-override to NUM.
228 top-queries
230 Shows the top-20 queries. Statistics are over the last
231 'stats-ringbuffer-entries' queries.
232 top-pub-queries
234 Shows the top-20 queries grouped by public suffix list. Statis‐
235 tics are over the last 'stats-ringbuffer-entries' queries.
236 top-largeanswer-remotes
238 Shows the top-20 remote hosts causing large answers. Statistics
239 are over the last 'stats-ringbuffer-entries' queries.
240 top-remotes
242 Shows the top-20 most active remote hosts. Statistics are over
243 the last 'stats-ringbuffer-entries' queries.
244 top-servfail-queries
246 Shows the top-20 queries causing servfail responses. Statistics
247 are over the last 'stats-ringbuffer-entries' queries.
248 top-bogus-queries
250 Shows the top-20 queries causing bogus responses. Statistics are
251 over the last 'stats-ringbuffer-entries' queries.
252 top-pub-servfail-queries
254 Shows the top-20 queries causing servfail responses grouped by
255 public suffix list. Statistics are over the last 'stats-ring‐
256 buffer-entries' queries.
257 top-pub-bogus-queries
259 Shows the top-20 queries causing bogus responses grouped by pub‐
260 lic suffix list. Statistics are over the last 'stats-ring‐
261 buffer-entries' queries.
262 top-servfail-remotes
264 Shows the top-20 most active remote hosts causing servfail re‐
265 sponses. Statistics are over the last 'stats-ringbuffer-en‐
266 tries' queries.
267 top-bogus-remotes
269 Shows the top-20 most active remote hosts causing bogus re‐
270 sponses. Statistics are over the last 'stats-ringbuffer-en‐
271 tries' queries.
272 top-timeouts
274 Shows the top-20 most active downstream timeout destinations.
275 Statistics are over the last 'stats-ringbuffer-entries' queries.
276 trace-regex REGEX
278 Emit resolution trace for matching queries. Empty regex to dis‐
279 able trace.
280 Queries matching this regular expression will generate volumi‐
282 nous tracing output. Be aware that matches from the packet cache
283 will still not generate tracing. To unset the regex, pass
284 trace-regex without a new regex.
285 The regular expression is matched against domain queries termi‐
287 nated with a dot. For example the regex 'powerdns.com$' will not
288 match a query for 'www.powerdns.com', since the attempted match
289 will be with 'www.powerdns.com.'.
290 In addition, since this is a regular expression, to exclusively
292 match queries for 'www.powerdns.com', one should escape the
293 dots: '^www\.powerdns\.com\.$'. Note that the single quotes
294 prevent further interpretation of the backslashes by the shell.
295 Multiple matches can be chained with the | operator. For exam‐
297 ple, to match all queries for Dutch (.nl) and German (.de) do‐
298 main names, use: '\.nl\.$|\.de\.$'.
299 unload-lua-script
301 Unloads Lua script if one was loaded.
302 version
304 Report running version.
305 wipe-cache DOMAIN [DOMAIN] [...]
307 Wipe entries for DOMAIN (exact name match) from the cache. This
308 is useful if, for example, an important server has a new IP ad‐
309 dress, but the TTL has not yet expired. Multiple domain names
310 can be passed. DOMAIN can be suffixed with a '$'. to delete the
311 whole tree from the cache. i.e. 'powerdns.com$' will remove all
312 cached entries under and including the powerdns.com name.
313 Note: this command also wipes the negative cache.
315 Warning: Don't just wipe "www.somedomain.com", its NS records or
317 CNAME target may still be undesired, so wipe "somedomain.com" as
318 well.
319 wipe-cache-typed qtype DOMAIN [DOMAIN] [...]
321 Same as wipe-cache, but only wipe records of type qtype.
322
324 pdns_recursor(1)
325
327 PowerDNS.COM BV
328
330 2001-2019, PowerDNS.COM BV
331 Jun 30, 2021 REC_CONTROL(1)