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
33 --help provide this helpful message.
34 --config-dir=<path>
36 Directory where the recursor.conf lives.
37 --config-name=<name>
39 Name of the virtual configuration.
40 --socket-dir=<path>
42 Where the controlsocket will live, please use --config-dir
43 instead.
44 --socket-pid=<pid>
46 When running in SMP mode, pid of pdns_recursor to control.
47 --timeout=<num>
49 Number of seconds to wait for the remote PowerDNS Recursor to
50 respond. Set to 0 for infinite.
51
53 add-nta DOMAIN [REASON]
54 Add a Negative Trust Anchor for DOMAIN, suffixed optionally with
55 REASON.
56 add-ta DOMAIN DSRECORD
58 Add a Trust Anchor for DOMAIN with DS record data DSRECORD. This
59 adds the new Trust Anchor to the existing set of Trust Anchors
60 for DOMAIN.
61 current-queries
63 Shows the currently active queries.
64 clear-nta DOMAIN...
66 Remove Negative Trust Anchor for one or more DOMAINs. Set domain
67 to '*' to remove all NTA's.
68 clear-ta [DOMAIN]...
70 Remove Trust Anchor for one or more DOMAINs. Note that removing
71 the root trust anchor is not possible.
72 dump-cache FILENAME
74 Dumps the entire cache to FILENAME. This file should not exist
75 already, PowerDNS will refuse to overwrite it. While dumping,
76 the recursor will not answer questions.
77 Typical PowerDNS Recursors run multiple threads, therefore
79 you'll see duplicate, different entries for the same domains.
80 The negative cache is also dumped to the same file. The
81 per-thread positive and negative cache dumps are separated with
82 an appropriate comment.
83 dump-edns FILENAME
85 Dumps the EDNS status to the filename mentioned. This file
86 should not exist already, PowerDNS will refuse to overwrite it.
87 While dumping, the recursor will not answer questions.
88 dump-nsspeeds FILENAME
90 Dumps the nameserver speed statistics to the FILENAME mentioned.
91 This file should not exist already, PowerDNS will refuse to
92 overwrite it. While dumping, the recursor will not answer ques‐
93 tions. Statistics are kept per thread, and the dumps end up in
94 the same file.
95 dump-rpz ZONE NAME FILE NAME
97 Dumps the content of the RPZ zone named ZONE NAME to the FILE‐
98 NAME mentioned. This file should not exist already, PowerDNS
99 will refuse to overwrite it otherwise. While dumping, the recur‐
100 sor will not answer questions.
101 get STATISTIC [STATISTIC]...
103 Retrieve a statistic. For items that can be queried, see ../met‐
104 rics
105 get-all
107 Retrieve all known statistics.
108 get-ntas
110 Get a list of the currently configured Negative Trust Anchors.
111 get-tas
113 Get a list of the currently configured Trust Anchors.
114 get-parameter KEY [KEY]...
116 Retrieves the specified configuration parameter(s).
117 get-qtypelist
119 Retrieves QType statistics. Queries from cache aren't being
120 counted yet.
121 help Shows a list of supported commands understood by the running
123 pdns_recursor
124 ping Check if server is alive.
126 quit Request shutdown of the recursor.
128 quit-nicely
130 Request nice shutdown of the recursor.
131 reload-acls
133 Reloads ACLs.
134 reload-lua-script [FILENAME]
136 (Re)loads Lua script FILENAME. If FILENAME is empty, attempt to
137 reload the currently loaded script. This replaces the script
138 currently loaded.
139 reload-lua-config [FILENAME]
141 (Re)loads Lua configuration FILENAME. If FILENAME is empty,
142 attempt to reload the currently loaded file. Note that FILENAME
143 will be fully executed, any settings changed at runtime that are
144 not modified in this file, will still be active. Reloading RPZ,
145 especially by AXFR, can take some time; during which the recur‐
146 sor will not answer questions.
147 reload-zones
149 Reload authoritative and forward zones. Retains current configu‐
150 ration in case of errors.
151 set-carbon-server CARBON SERVER [CARBON OURNAME]
153 Set the carbon-server setting to CARBON SERVER. If CARBON OUR‐
154 NAME is not empty, also set the carbon-ourname setting to CARBON
155 OURNAME.
156 set-dnssec-log-bogus SETTING
158 Set dnssec-log-bogus setting to SETTING. Set to 'on' or 'yes' to
159 log DNSSEC validation failures and to 'no' or 'off' to disable
160 logging these failures.
161 set-max-cache-entries NUM
163 Change the maximum number of entries in the DNS cache. If
164 reduced, the cache size will start shrinking to this number as
165 part of the normal cache purging process, which might take a
166 while.
167 set-max-packetcache-entries NUM
169 Change the maximum number of entries in the packet cache. If
170 reduced, the cache size will start shrinking to this number as
171 part of the normal cache purging process, which might take a
172 while.
173 set-minimum-ttl NUM
175 Set minimum-ttl-override to NUM.
176 top-queries
178 Shows the top-20 queries. Statistics are over the last
179 'stats-ringbuffer-entries' queries.
180 top-pub-queries
182 Shows the top-20 queries grouped by public suffix list. Statis‐
183 tics are over the last 'stats-ringbuffer-entries' queries.
184 top-largeanswer-remotes
186 Shows the top-20 remote hosts causing large answers. Statistics
187 are over the last 'stats-ringbuffer-entries' queries.
188 top-remotes
190 Shows the top-20 most active remote hosts. Statistics are over
191 the last 'stats-ringbuffer-entries' queries.
192 top-servfail-queries
194 Shows the top-20 queries causing servfail responses. Statistics
195 are over the last 'stats-ringbuffer-entries' queries.
196 top-pub-servfail-queries
198 Shows the top-20 queries causing servfail responses grouped by
199 public suffix list. Statistics are over the last 'stats-ring‐
200 buffer-entries' queries.
201 top-servfail-remotes
203 Shows the top-20 most active remote hosts causing servfail
204 responses. Statistics are over the last 'stats-ring‐
205 buffer-entries' queries.
206 trace-regex REGEX
208 Emit resolution trace for matching queries. Empty regex to dis‐
209 able trace.
210 Queries matching this regular expression will generate volumi‐
212 nous tracing output. Be aware that matches from the packet cache
213 will still not generate tracing. To unset the regex, pass
214 trace-regex without a new regex.
215 The regular expression is matched against domain queries termi‐
217 nated with a '.'. For example the regex 'powerdns.com$' will not
218 match a query for 'www.powerdns.com', since the attempted match
219 will be with 'www.powerdns.com.'.
220 In addition, since this is a regular expression, to exclusively
222 match queries for 'www.powerdns.com', one should escape the
223 dots: '^www.powerdns.com.$'.
224 Multiple matches can be chained with the '|' operator. For exam‐
226 ple, to match all queries for Dutch (.nl) and German (.de)
227 domain names, use: '.nl.$|.de.$'.
228 unload-lua-script
230 Unloads Lua script if one was loaded.
231 version
233 Report running version.
234 wipe-cache DOMAIN [DOMAIN] [...]
236 Wipe entries for DOMAIN (exact name match) from the cache. This
237 is useful if, for example, an important server has a new IP
238 address, but the TTL has not yet expired. Multiple domain names
239 can be passed. DOMAIN can be suffixed with a '$'. to delete the
240 whole tree from the cache. i.e. 'powerdns.com$' will remove all
241 cached entries under and including the powerdns.com name.
242 Note: this command also wipes the negative cache.
244 Warning: Don't just wipe "www.somedomain.com", its NS records or
246 CNAME target may still be undesired, so wipe "somedomain.com" as
247 well.
248
250 pdns_recursor(1)
251
253 PowerDNS.COM BV
254
256 2001-2018, PowerDNS.COM BV
2574.1 Jan 21, 2019 REC_CONTROL(1)