1REC_CONTROL(1)                 PowerDNS Recursor                REC_CONTROL(1)
2
3
4

NAME

6       rec_control - Command line tool to control a running Recursor
7

SYNOPSIS

9       rec_control [OPTION]... COMMAND [COMMAND-OPTION]...
10

DESCRIPTION

12       rec_control allows the operator to query and control a running instance
13       of the PowerDNS Recursor.
14
15       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

EXAMPLES

20       To see if the Recursor is alive, run:
21
22          # rec_control ping
23
24       To stop the recursor by hand, run:
25
26          # rec_control quit
27
28       To dump the cache to disk, execute:
29
30          # rec_control dump-cache /tmp/the-cache
31

OPTIONS

33       --help provide this helpful message.
34
35       --config-dir=<path>
36              Directory where the recursor.conf lives.
37
38       --config-name=<name>
39              Name of the virtual configuration.
40
41       --socket-dir=<path>
42              Where the  controlsocket  will  live,  please  use  --config-dir
43              instead.
44
45       --socket-pid=<pid>
46              When running in SMP mode, pid of pdns_recursor to control.
47
48       --timeout=<num>
49              Number  of  seconds  to wait for the remote PowerDNS Recursor to
50              respond. Set to 0 for infinite.
51

COMMANDS

53       add-dont-throttle-names NAME [NAME...]
54              Add names for nameserver domains that may not be throttled.
55
56       add-dont-throttle-netmasks NETMASK [NETMASK...]
57              Add netmasks for nameservers that may not be throttled.
58
59       add-nta DOMAIN [REASON]
60              Add a Negative Trust Anchor for DOMAIN, suffixed optionally with
61              REASON.
62
63       add-ta DOMAIN DSRECORD
64              Add a Trust Anchor for DOMAIN with DS record data DSRECORD. This
65              adds the new Trust Anchor to the existing set of  Trust  Anchors
66              for DOMAIN.
67
68       current-queries
69              Shows the currently active queries.
70
71       clear-dont-throttle-names NAME [NAME...]
72              Remove  names  that  are not allowed to be throttled. If NAME is
73              '*', remove all
74
75       clear-dont-throttle-netmasks NETMASK [NETMASK...]
76              Remove netmasks that are not allowed to be throttled. If NETMASK
77              is '*', remove all
78
79       clear-nta DOMAIN...
80              Remove Negative Trust Anchor for one or more DOMAINs. Set domain
81              to '*' to remove all NTA's.
82
83       clear-ta [DOMAIN]...
84              Remove Trust Anchor for one or more DOMAINs. Note that  removing
85              the root trust anchor is not possible.
86
87       dump-cache FILENAME
88              Dumps  the  entire cache to FILENAME. This file should not exist
89              already, PowerDNS will refuse to overwrite  it.  While  dumping,
90              the recursor will not answer questions.
91
92              Typical  PowerDNS  Recursors  run  multiple  threads,  therefore
93              you'll see duplicate, different entries for  the  same  domains.
94              The  negative  cache  is  also  dumped  to  the  same  file. The
95              per-thread positive and negative cache dumps are separated  with
96              an appropriate comment.
97
98              NOTE:
99                 pdns_recursor  often  runs  in a chroot. You can retrieve the
100                 file using:
101
102                     rec_control dump-cache /tmp/file
103                     mv /proc/$(pidof pdns_recursor)/root/tmp/file /tmp/filename
104
105       dump-edns FILENAME
106              Dumps the EDNS status  to  the  filename  mentioned.  This  file
107              should  not exist already, PowerDNS will refuse to overwrite it.
108              While dumping, the recursor will not answer questions.
109
110              NOTE:
111                 pdns_recursor often runs in a chroot. You  can  retrieve  the
112                 file using:
113
114                     rec_control dump-edns /tmp/file
115                     mv /proc/$(pidof pdns_recursor)/root/tmp/file /tmp/filename
116
117       dump-nsspeeds FILENAME
118              Dumps the nameserver speed statistics to the FILENAME mentioned.
119              This file should not exist  already,  PowerDNS  will  refuse  to
120              overwrite  it. While dumping, the recursor will not answer ques‐
121              tions. Statistics are kept per thread, and the dumps end  up  in
122              the same file.
123
124              NOTE:
125                 pdns_recursor  often  runs  in a chroot. You can retrieve the
126                 file using:
127
128                     rec_control dump-nsspeeds /tmp/file
129                     mv /proc/$(pidof pdns_recursor)/root/tmp/file /tmp/filename
130
131       dump-rpz ZONE NAME FILE NAME
132              Dumps the content of the RPZ zone named ZONE NAME to  the  FILE‐
133              NAME  mentioned.  This  file  should not exist already, PowerDNS
134              will refuse to overwrite it otherwise. While dumping, the recur‐
135              sor will not answer questions.
136
137              NOTE:
138                 pdns_recursor  often  runs  in a chroot. You can retrieve the
139                 file using:
140
141                     rec_control dump-rpz ZONE_NAME /tmp/file
142                     mv /proc/$(pidof pdns_recursor)/root/tmp/file /tmp/filename
143
144       dump-throttlemap FILENAME
145              Dump the contents of the throttle map to the FILENAME mentioned.
146              This  file  should  not  exist  already, PowerDNS will refuse to
147              overwrite it otherwise. While dumping,  the  recursor  will  not
148              answer questions.
149
150              NOTE:
151                 pdns_recursor  often  runs  in a chroot. You can retrieve the
152                 file using:
153
154                     rec_control dump-throttlemap /tmp/file
155                     mv /proc/$(pidof pdns_recursor)/root/tmp/file /tmp/filename
156
157       dump-failedservers FILENAME
158              Dump the contents of the failed server map to the FILENAME  men‐
159              tioned.   This  file  should  not  exist  already, PowerDNS will
160              refuse to overwrite it otherwise. While  dumping,  the  recursor
161              will not answer questions.
162
163              NOTE:
164                 pdns_recursor  often  runs  in a chroot. You can retrieve the
165                 file using:
166
167                     rec_control dump-failedservers /tmp/file
168                     mv /proc/$(pidof pdns_recursor)/root/tmp/file /tmp/filename
169
170       get STATISTIC [STATISTIC]...
171              Retrieve a statistic. For items that can be queried, see ../met‐
172              rics
173
174       get-all
175              Retrieve all known statistics.
176
177       get-dont-throttle-names
178              Get the list of names that are not allowed to be throttled.
179
180       get-dont-throttle-netmasks
181              Get the list of netmasks that are not allowed to be throttled.
182
183       get-ntas
184              Get a list of the currently configured Negative Trust Anchors.
185
186       get-tas
187              Get a list of the currently configured Trust Anchors.
188
189       get-parameter KEY [KEY]...
190              Retrieves the specified configuration parameter(s).
191
192       get-qtypelist
193              Retrieves  QType  statistics.  Queries  from  cache aren't being
194              counted yet.
195
196       help   Shows a list of supported commands  understood  by  the  running
197              pdns_recursor
198
199       ping   Check if server is alive.
200
201       quit   Request shutdown of the recursor.
202
203       quit-nicely
204              Request nice shutdown of the recursor.
205
206       reload-acls
207              Reloads ACLs.
208
209       reload-lua-script [FILENAME]
210              (Re)loads  Lua script FILENAME. If FILENAME is empty, attempt to
211              reload the currently loaded script.  This  replaces  the  script
212              currently loaded.
213
214       reload-lua-config [FILENAME]
215              (Re)loads  Lua  configuration  FILENAME.  If  FILENAME is empty,
216              attempt to reload the currently loaded file. Note that  FILENAME
217              will be fully executed, any settings changed at runtime that are
218              not modified in this file, will still be active. Reloading  RPZ,
219              especially  by AXFR, can take some time; during which the recur‐
220              sor will not answer questions.
221
222       reload-zones
223              Reload authoritative and forward zones. Retains current configu‐
224              ration in case of errors.
225
226       set-carbon-server CARBON SERVER [CARBON OURNAME]
227              Set  the  carbon-server setting to CARBON SERVER. If CARBON OUR‐
228              NAME is not empty, also set the carbon-ourname setting to CARBON
229              OURNAME.
230
231       set-dnssec-log-bogus SETTING
232              Set dnssec-log-bogus setting to SETTING. Set to 'on' or 'yes' to
233              log DNSSEC validation failures and to 'no' or 'off'  to  disable
234              logging these failures.
235
236       set-ecs-minimum-ttl NUM
237              Set ecs-minimum-ttl-override to NUM.
238
239       set-max-cache-entries NUM
240              Change  the  maximum  number  of  entries  in the DNS cache.  If
241              reduced, the cache size will start shrinking to this  number  as
242              part  of  the  normal  cache purging process, which might take a
243              while.
244
245       set-max-packetcache-entries NUM
246              Change the maximum number of entries in the  packet  cache.   If
247              reduced,  the  cache size will start shrinking to this number as
248              part of the normal cache purging process,  which  might  take  a
249              while.
250
251       set-minimum-ttl NUM
252              Set minimum-ttl-override to NUM.
253
254       top-queries
255              Shows   the   top-20  queries.  Statistics  are  over  the  last
256              'stats-ringbuffer-entries' queries.
257
258       top-pub-queries
259              Shows the top-20 queries grouped by public suffix list.  Statis‐
260              tics are over the last 'stats-ringbuffer-entries' queries.
261
262       top-largeanswer-remotes
263              Shows  the top-20 remote hosts causing large answers. Statistics
264              are over the last 'stats-ringbuffer-entries' queries.
265
266       top-remotes
267              Shows the top-20 most active remote hosts. Statistics  are  over
268              the last 'stats-ringbuffer-entries' queries.
269
270       top-servfail-queries
271              Shows  the top-20 queries causing servfail responses. Statistics
272              are over the last 'stats-ringbuffer-entries' queries.
273
274       top-bogus-queries
275              Shows the top-20 queries causing bogus responses. Statistics are
276              over the last 'stats-ringbuffer-entries' queries.
277
278       top-pub-servfail-queries
279              Shows  the  top-20 queries causing servfail responses grouped by
280              public suffix list. Statistics are over  the  last  'stats-ring‐
281              buffer-entries' queries.
282
283       top-pub-bogus-queries
284              Shows the top-20 queries causing bogus responses grouped by pub‐
285              lic suffix list.  Statistics  are  over  the  last  'stats-ring‐
286              buffer-entries' queries.
287
288       top-servfail-remotes
289              Shows  the  top-20  most  active  remote  hosts causing servfail
290              responses.   Statistics   are   over   the   last   'stats-ring‐
291              buffer-entries' queries.
292
293       top-bogus-remotes
294              Shows   the  top-20  most  active  remote  hosts  causing  bogus
295              responses.   Statistics   are   over   the   last   'stats-ring‐
296              buffer-entries' queries.
297
298       top-timeouts
299              Shows  the  top-20  most active downstream timeout destinations.
300              Statistics are over the last 'stats-ringbuffer-entries' queries.
301
302       trace-regex REGEX
303              Emit resolution trace for matching queries. Empty regex to  dis‐
304              able trace.
305
306              Queries  matching  this regular expression will generate volumi‐
307              nous tracing output. Be aware that matches from the packet cache
308              will  still  not  generate  tracing.  To  unset  the regex, pass
309              trace-regex without a new regex.
310
311              The regular expression is matched against domain queries  termi‐
312              nated with a '.'. For example the regex 'powerdns.com$' will not
313              match a query for 'www.powerdns.com', since the attempted  match
314              will be with 'www.powerdns.com.'.
315
316              In  addition, since this is a regular expression, to exclusively
317              match queries for  'www.powerdns.com',  one  should  escape  the
318              dots: '^www.powerdns.com.$'.
319
320              Multiple matches can be chained with the '|' operator. For exam‐
321              ple, to match all queries  for  Dutch  (.nl)  and  German  (.de)
322              domain names, use: '.nl.$|.de.$'.
323
324       unload-lua-script
325              Unloads Lua script if one was loaded.
326
327       version
328              Report running version.
329
330       wipe-cache DOMAIN [DOMAIN] [...]
331              Wipe  entries for DOMAIN (exact name match) from the cache. This
332              is useful if, for example, an important  server  has  a  new  IP
333              address,  but the TTL has not yet expired. Multiple domain names
334              can be passed.  DOMAIN can be suffixed with a '$'. to delete the
335              whole  tree from the cache. i.e. 'powerdns.com$' will remove all
336              cached entries under and including the powerdns.com name.
337
338              Note: this command also wipes the negative cache.
339
340              Warning: Don't just wipe "www.somedomain.com", its NS records or
341              CNAME target may still be undesired, so wipe "somedomain.com" as
342              well.
343

SEE ALSO

345       pdns_recursor(1)
346

AUTHOR

348       PowerDNS.COM BV
349
351       2001-2019, PowerDNS.COM BV
352
353
354
355
356                                 Nov 24, 2020                   REC_CONTROL(1)
Impressum