Controlling and querying the recursor
To control and query the PowerDNS recursor, the tool
rec_control is provided. This program talks to the recursor over the 'controlsocket', often stored in
As a sample command, try:
# rec_control ping pong
When not running as root,
--socket-dir=/tmp might be appropriate.
dump-cache filename Dumps the entire cache to the filename mentioned. This file should not exist already, PowerDNS will refuse to overwrite it. While dumping, the recursor will not answer questions.
Show currently outstanding queries.
Dump cache contents to the named file
filename. Note that the file MUST NOT exist beforehand. \
Typical PowerDNS Recursors run multiple threads, therefore you'll see duplicate, different entries for the same domains. The negative cache is also dumped to the same file. The per-thread positive and negative cache dumps are separated with an appropriate comment.
Dump EDNS Status for remotes to the named file
filename. Note that the file MUST NOT exist beforehand.
Dump remote nameserver speed statistics to the named file
filename. Note that the file MUST NOT exist beforehand. Again, statistics are kept per thread, and the dumps end up in the same file.
Retrieve a statistic. For items that can be queried, see below.
Retrieve all statistics in one go. Available since version 3.2.
get-parameter parameter1 [parameter2 ..]
Retrieve a configuration parameter. All parameters from the configuration and command line can be queried. Available since version 3.2.
List all commands understood by your running
Check if server is alive.
Request shutdown of the recursor.
Request a nice shutdown of the recursor.
Reload access control lists.
(Re-)Load Lua script. Note that loading a script fully replaces the one currently loaded.
(Re-)Load the Lua configuration file. Note that FILENAME will be fully executed, any settings changed at runtime that are not modified in this file, will still be active. Also note that the process will block (not answering queries) when reloading, this might take a long time when an RPZ has to be transferred.
Reload data about all authoritative and forward zones. The configuration file is also scanned to see if the auth-domain, forward-domain and export-etc-hosts statements have changed, and if so, these changes are incorporated.
Available since 3.6, this setting artificially raises all TTLs to be at least this long. While this is a gross hack, and violates RFCs, under conditions of DoS, it may enable you to continue serving your customers. Corresponds to the configuration file setting 'minimum-ttl-override'.
set-carbon-server server ourname
Set a Carbon server for telemetry purposes. The parameter
server corresponds to the configuration setting carbon-server, and
ourname corresponds to carbon-ourname.
Shows the top-20 most active remote hosts. Statistics are over the last stats-ringbuffer-entries queries.
Available since 3.5.
Queries matching this regular expression will generate voluminous tracing output. Be aware that matches from the packet cache will still not generate tracing. To unset the regex, pass
trace-regex without a new regex.
The regular expression is matched against domain queries terminated with a
.. So, for example the regex
powerdns\.com$ will not match a query for
www.powerdns.com, since the attempted match will be with
In addition, since this is a regular expression, to exclusively match queries for
www.powerdns.com, one should escape the dots:
Multiple matches can be chained with the | operator. For example, to match all queries for Dutch (.nl) and German (.de) domain names, use:
Unload Lua script, if one is loaded.
Available after 3.6.1, report currently running version.
wipe-cache domain1. [domain2. ..]
Wipe entries from the cache. This is useful if, for example, an important server has a new IP address, but the TTL has not yet expired. Multiple domain names can be passed. For versions before 3.1, you must terminate a domain with a
.! So to wipe powerdns.org, issue
rec_control wipe-cache powerdns.org.. For later versions, the dot is optional.
To wipe all subdomain entries, append a $ at the end for example
powerdns.com$ would wipe that domain as well as
Note that deletion is exact, wiping
com. will leave
Warning: As of 3.1.7, this command also wipes the negative query cache for the specified domain. Warning: Don't just wipe "www.somedomain.com", its NS records or CNAME target may still be undesired, so wipe "somedomain.com" as well.
get can query a large number of statistics, which are detailed in Performance Monitoring.
More details on what "throttled" queries and the like are can be found below in Security Settings.