pdns/recursordist/docs/manpages/rec_control.1.rst

   1 rec_control
   2 ===========
   3
   4 Synopsis
   5 --------
   6
   7 **rec_control** [*OPTION*]... *COMMAND* [*COMMAND-OPTION*]...
   8
   9 Description
  10 -----------
  11
  12 :program:`rec_control` allows the operator to query and control a running
  13 instance of the PowerDNS Recursor.
  14
  15 :program:`rec_control` talks to the recursor via a the 'controlsocket'. Which
  16 is usually located in ``/var/run`` . The *--socket-dir* or the *--config-dir*
  17 and *--config-name* switches control to which process :program:`rec_control`
  18 connects.
  19
  20 Examples
  21 --------
  22 To see if the Recursor is alive, run::
  23
  24   # rec_control ping
  25
  26 To stop the recursor by hand, run::
  27
  28   # rec_control quit
  29
  30 To dump the cache to disk, execute::
  31
  32   # rec_control dump-cache /tmp/the-cache
  33
  34 .. note::
  35
  36   Before version 4.5.0, for each command that writes to a file, :program:`pdns_recursor` would open the file to write to.
  37   Starting with 4.5.0, the files are opened by the :program:`rec_control` command itself using the credentials and the current working directory of the user running :program:`rec_control`.
  38   A single minus *-* can be used as a filename to write the data to the standard output stream.
  39
  40 Options
  41 -------
  42 --help                provide this helpful message.
  43 --config-dir=<path>   Directory where the recursor.conf lives.
  44 --config-name=<name>  Name of the virtual configuration.
  45 --socket-dir=<path>   Where the controlsocket will live, please
  46                       use **--config-dir** instead.
  47 --socket-pid=<pid>    When running in SMP mode, pid of **pdns_recursor** to
  48                       control.
  49 --timeout=<num>       Number of seconds to wait for the remote PowerDNS
  50                       Recursor to respond.
  51
  52 Commands
  53 --------
  54 add-dont-throttle-names NAME [NAME...]
  55     Add names for nameserver domains that may not be throttled.
  56
  57 add-dont-throttle-netmasks NETMASK [NETMASK...]
  58     Add netmasks for nameservers that may not be throttled.
  59
  60 add-nta *DOMAIN* [*REASON*]
  61     Add a Negative Trust Anchor for *DOMAIN*, suffixed optionally with
  62     *REASON*.
  63
  64 add-ta *DOMAIN* *DSRECORD*
  65     Add a Trust Anchor for *DOMAIN* with DS record data *DSRECORD*. This adds
  66     the new Trust Anchor to the existing set of Trust Anchors 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 ``*``, remove all
  73
  74 clear-dont-throttle-netmasks NETMASK [NETMASK...]
  75     Remove netmasks that are not allowed to be throttled. If *NETMASK* is ``*``, remove all
  76
  77 clear-nta *DOMAIN*...
  78     Remove Negative Trust Anchor for one or more *DOMAIN*\ s. Set domain to
  79     ``*`` to remove all NTA's.
  80
  81 clear-ta [*DOMAIN*]...
  82     Remove Trust Anchor for one or more *DOMAIN*\ s. Note that removing the
  83     root trust anchor is not possible.
  84
  85 dump-cache *FILENAME*
  86     Dumps the entire cache to *FILENAME*. This file should not exist already,
  87     PowerDNS will refuse to overwrite it. While dumping, the recursor
  88     might not answer questions.
  89
  90     Typical PowerDNS Recursors run multiple threads, therefore you'll see
  91     duplicate, different entries for the same domains. The negative cache is
  92     also dumped to the same file. The per-thread positive and negative cache
  93     dumps are separated with an appropriate comment.
  94
  95 dump-dot-probe-map *FILENAME*
  96     Dump the contents of the DoT probe map to the *FILENAME* mentioned.
  97
  98 dump-edns *FILENAME*
  99     Dumps the EDNS status to the filename mentioned. This file should not exist
 100     already, PowerDNS will refuse to overwrite it. While dumping, the recursor
 101     will not answer questions.
 102
 103 dump-failedservers *FILENAME*
 104     Dump the contents of the failed server map to the *FILENAME* mentioned.
 105     This file should not exist already, PowerDNS will refuse to
 106     overwrite it otherwise. While dumping, the recursor will not answer
 107     questions.
 108
 109 dump-non-resolving *FILENAME*
 110     Dump the contents of the map of nameserver names that did not resolve to
 111     an address.  This file should not exist already, PowerDNS will
 112     refuse to overwrite it otherwise. While dumping, the recursor will
 113     not answer questions.
 114
 115 dump-nsspeeds *FILENAME*
 116     Dumps the nameserver speed statistics to the *FILENAME* mentioned. This
 117     file should not exist already, PowerDNS will refuse to overwrite it. While
 118     dumping, the recursor will not answer questions. Statistics are kept per
 119     thread, and the dumps end up in the same file.
 120
 121 dump-rpz *ZONE NAME* *FILE NAME*
 122     Dumps the content of the RPZ zone named *ZONE NAME* to the *FILENAME*
 123     mentioned. This file should not exist already, PowerDNS will refuse to
 124     overwrite it otherwise. While dumping, the recursor will not answer
 125     questions. For details on how RPZ are named see
 126     `<https://docs.powerdns.com/recursor/lua-config/rpz.html#policyname>`__.
 127
 128 dump-saved-parent-ns-sets *FILE NAME*
 129     Dump the entries of the map containing saved parent NS sets
 130     that were successfully used in resolving.
 131     The total number of entries is also printed in the header.
 132     An entry is saved if the recursor sees that the parent set includes
 133     names not in the child set. This is an indication of a
 134     misconfigured domain.
 135
 136 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 answer
 140     questions.
 141
 142 get *STATISTIC* [*STATISTIC*]...
 143     Retrieve a statistic. For items that can be queried, see
 144     `<https://docs.powerdns.com/recursor/metrics.html>`__.
 145
 146 get-all
 147     Retrieve all known statistics.
 148
 149 get-dont-throttle-names
 150     Get the list of names that are not allowed to be throttled.
 151
 152 get-dont-throttle-netmasks
 153     Get the list of netmasks that are not allowed to be throttled.
 154
 155 get-ntas
 156     Get a list of the currently configured Negative Trust Anchors.
 157
 158 get-tas
 159     Get a list of the currently configured Trust Anchors.
 160
 161 get-parameter *KEY* [*KEY*]...
 162     Retrieves the specified configuration parameter(s).
 163
 164 get-proxymapping-stats
 165     Get the list of proxy-mapped subnets and associated counters.
 166
 167 get-qtypelist
 168     Retrieves QType statistics. Queries from cache aren't being counted yet.
 169
 170 get-remotelogger-stats
 171     Retrieves the remote logger statistics, per type and address.
 172
 173 hash-password [*WORK-FACTOR*]
 174     Asks for a password then returns the hashed and salted version,
 175     to use as a webserver password or API key. This command does
 176     not contact the recursor but does the hashing inside rec_control.
 177     An optional scrypt work factor can be specified, in power of two.
 178     The default is 1024.
 179
 180 help
 181     Shows a list of supported commands understood by the running
 182     :program:`pdns_recursor`
 183
 184 list-dnssec-algos
 185     List supported (and potentially disabled) DNSSEC algorithms.
 186
 187 ping
 188     Check if server is alive.
 189
 190 quit
 191     Request shutdown of the recursor, exiting the process while
 192     letting the OS clean up resources.
 193
 194 quit-nicely
 195     Request nice shutdown of the recursor. This method allows all
 196     threads to finish their current work and releases resources before
 197     exiting. This is the preferred method to stop the recursor.
 198
 199 reload-acls
 200     Reloads ACLs.
 201
 202 reload-lua-script [*FILENAME*]
 203     (Re)loads Lua script *FILENAME*. If *FILENAME* is empty, attempt to reload
 204     the currently loaded script. This replaces the script currently loaded.
 205
 206 reload-lua-config [*FILENAME*]
 207     (Re)loads Lua configuration *FILENAME*. If *FILENAME* is empty, attempt
 208     to reload the currently loaded file. Note that *FILENAME* will be fully
 209     executed, any settings changed at runtime that are not modified in this
 210     file, will still be active. The effects of reloading do not always take
 211     place immediately, as some subsystems reload and replace configuration
 212     in an asynchronous way.
 213
 214 reload-zones
 215     Reload authoritative and forward zones. Retains current configuration in
 216     case of errors.
 217
 218 set-carbon-server *CARBON SERVER* [*CARBON OURNAME*]
 219     Set the carbon-server setting to *CARBON SERVER*. If *CARBON OURNAME* is
 220     not empty, also set the carbon-ourname setting to *CARBON OURNAME*.
 221
 222 set-dnssec-log-bogus *SETTING*
 223     Set dnssec-log-bogus setting to *SETTING*. Set to ``on`` or ``yes`` to log
 224     DNSSEC validation failures and to ``no`` or ``off`` to disable logging these
 225     failures.
 226
 227 set-ecs-minimum-ttl *NUM*
 228     Set ecs-minimum-ttl-override to *NUM*.
 229
 230 set-max-cache-entries *NUM*
 231     Change the maximum number of entries in the DNS cache.  If reduced, the
 232     cache size will start shrinking to this number as part of the normal
 233     cache purging process, which might take a while.
 234
 235 set-max-packetcache-entries *NUM*
 236     Change the maximum number of entries in the packet cache.  If reduced, the
 237     cache size will start shrinking to this number as part of the normal
 238     cache purging process, which might take a while.
 239
 240 set-minimum-ttl *NUM*
 241     Set minimum-ttl-override to *NUM*.
 242
 243 set-event-trace-enabled *NUM*
 244     Set logging of event trace messages, ``0`` = disabled, ``1`` = protobuf,
 245     ``2`` = log file, ``3`` = protobuf and log file.
 246
 247 show-yaml [*FILE*]
 248     Show Yaml representation of odl-style config.
 249
 250 top-queries
 251     Shows the top-20 queries. Statistics are over the last
 252     'stats-ringbuffer-entries' queries.
 253
 254 top-pub-queries
 255     Shows the top-20 queries grouped by public suffix list. Statistics are over
 256     the last 'stats-ringbuffer-entries' queries.
 257
 258 top-largeanswer-remotes
 259     Shows the top-20 remote hosts causing large answers. Statistics are over
 260     the last 'stats-ringbuffer-entries' queries.
 261
 262 top-remotes
 263     Shows the top-20 most active remote hosts. Statistics are over the last
 264     'stats-ringbuffer-entries' queries.
 265
 266 top-servfail-queries
 267     Shows the top-20 queries causing servfail responses. Statistics are over
 268     the last 'stats-ringbuffer-entries' queries.
 269
 270 top-bogus-queries
 271     Shows the top-20 queries causing bogus responses. Statistics are over
 272     the last 'stats-ringbuffer-entries' queries.
 273
 274 top-pub-servfail-queries
 275     Shows the top-20 queries causing servfail responses grouped by public
 276     suffix list. Statistics are over the last 'stats-ringbuffer-entries'
 277     queries.
 278
 279 top-pub-bogus-queries
 280     Shows the top-20 queries causing bogus responses grouped by public
 281     suffix list. Statistics are over the last 'stats-ringbuffer-entries'
 282     queries.
 283
 284 top-servfail-remotes
 285     Shows the top-20 most active remote hosts causing servfail responses.
 286     Statistics are over the last 'stats-ringbuffer-entries' queries.
 287
 288 top-bogus-remotes
 289     Shows the top-20 most active remote hosts causing bogus responses.
 290     Statistics are over the last 'stats-ringbuffer-entries' queries.
 291
 292 top-timeouts
 293     Shows the top-20 most active downstream timeout destinations.
 294     Statistics are over the last 'stats-ringbuffer-entries' queries.
 295
 296 trace-regex *REGEX* *FILE*
 297     Emit resolution trace for matching queries. No arguments disables tracing.
 298     Before version 4.9.0, there was no *FILE* argument, traces were always
 299     written to the log. Starting with version 4.9.0, trace information is
 300     written to the file specified, which may be ``-`` for the standard out
 301     stream.
 302
 303     Queries matching this regular expression will generate voluminous tracing
 304     output. Be aware that matches from the packet cache will still not generate
 305     tracing. To unset the regex, pass **trace-regex** without a new regex.
 306
 307     The regular expression is matched against domain queries terminated with a
 308     dot. For example the regex ``'powerdns.com$'`` will not match a query for
 309     ``'www.powerdns.com'``, since the attempted match will be with
 310     ``'www.powerdns.com.'``.
 311
 312     In addition, since this is a regular expression, to exclusively match
 313     queries for ``'www.powerdns.com'``, one should escape the dots:
 314     ``'^www\.powerdns\.com\.$'``.
 315     Note that the single quotes prevent
 316     further interpretation of the backslashes by the shell.
 317
 318     Multiple matches can be chained with the ``|`` operator. For example, to
 319     match all queries for Dutch (``.nl``) and German (``.de``) domain names, use:
 320     ``'\.nl\.$|\.de\.$'``.
 321
 322 unload-lua-script
 323     Unloads Lua script if one was loaded.
 324
 325 version
 326     Report running version.
 327
 328 wipe-cache *DOMAIN* [*DOMAIN*] [...]
 329     Wipe entries for *DOMAIN* (exact name match) from the cache. This is useful
 330     if, for example, an important server has a new IP address, but the TTL has
 331     not yet expired. Multiple domain names can be passed.
 332     *DOMAIN* can be suffixed with a ``$``. to delete the whole tree from the
 333     cache. i.e. ``powerdns.com$`` will remove all cached entries under and
 334     including the powerdns.com name.
 335
 336     **Note**: this command also wipes the negative cache.
 337
 338     **Warning**: Don't just wipe "www.somedomain.com", its NS records or CNAME
 339     target may still be undesired, so wipe "somedomain.com" as well.
 340
 341 wipe-cache-typed *qtype* *DOMAIN* [*DOMAIN*] [...]
 342     Same as wipe-cache, but only wipe records of type *qtype*.
 343
 344 See also
 345 --------
 346 :manpage:`pdns_recursor(1)`
 347 `<https://docs.powerdns.com/recursor>`__