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-nta DOMAIN [REASON]
54              Add a Negative Trust Anchor for DOMAIN, suffixed optionally with
55              REASON.
56
57       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
62       current-queries
63              Shows the currently active queries.
64
65       clear-nta DOMAIN...
66              Remove Negative Trust Anchor for one or more DOMAINs. Set domain
67              to '*' to remove all NTA's.
68
69       clear-ta [DOMAIN]...
70              Remove Trust Anchor for one or more DOMAINs. Note that  removing
71              the root trust anchor is not possible.
72
73       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
78              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
84       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
89       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
96       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
102       get STATISTIC [STATISTIC]...
103              Retrieve a statistic. For items that can be queried, see ../met‐
104              rics
105
106       get-all
107              Retrieve all known statistics.
108
109       get-ntas
110              Get a list of the currently configured Negative Trust Anchors.
111
112       get-tas
113              Get a list of the currently configured Trust Anchors.
114
115       get-parameter KEY [KEY]...
116              Retrieves the specified configuration parameter(s).
117
118       get-qtypelist
119              Retrieves  QType  statistics.  Queries  from  cache aren't being
120              counted yet.
121
122       help   Shows a list of supported commands  understood  by  the  running
123              pdns_recursor
124
125       ping   Check if server is alive.
126
127       quit   Request shutdown of the recursor.
128
129       quit-nicely
130              Request nice shutdown of the recursor.
131
132       reload-acls
133              Reloads ACLs.
134
135       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
140       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
148       reload-zones
149              Reload authoritative and forward zones. Retains current configu‐
150              ration in case of errors.
151
152       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
157       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
162       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
168       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
174       set-minimum-ttl NUM
175              Set minimum-ttl-override to NUM.
176
177       top-queries
178              Shows   the   top-20  queries.  Statistics  are  over  the  last
179              'stats-ringbuffer-entries' queries.
180
181       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
185       top-largeanswer-remotes
186              Shows  the top-20 remote hosts causing large answers. Statistics
187              are over the last 'stats-ringbuffer-entries' queries.
188
189       top-remotes
190              Shows the top-20 most active remote hosts. Statistics  are  over
191              the last 'stats-ringbuffer-entries' queries.
192
193       top-servfail-queries
194              Shows  the top-20 queries causing servfail responses. Statistics
195              are over the last 'stats-ringbuffer-entries' queries.
196
197       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
202       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
207       trace-regex REGEX
208              Emit resolution trace for matching queries. Empty regex to  dis‐
209              able trace.
210
211              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
216              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
221              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
225              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
229       unload-lua-script
230              Unloads Lua script if one was loaded.
231
232       version
233              Report running version.
234
235       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
243              Note: this command also wipes the negative cache.
244
245              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

SEE ALSO

250       pdns_recursor(1)
251

AUTHOR

253       PowerDNS.COM BV
254
256       2001-2018, PowerDNS.COM BV
257
258
259
260
2614.1                              Jan 21, 2019                   REC_CONTROL(1)
Impressum