You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 

476 lines
14 KiB

  1. .\" Man page generated from reStructuredText.
  2. .
  3. .TH "REC_CONTROL" "1" "Dec 11, 2020" "" "PowerDNS Recursor"
  4. .SH NAME
  5. rec_control \- Command line tool to control a running Recursor
  6. .
  7. .nr rst2man-indent-level 0
  8. .
  9. .de1 rstReportMargin
  10. \\$1 \\n[an-margin]
  11. level \\n[rst2man-indent-level]
  12. level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
  13. -
  14. \\n[rst2man-indent0]
  15. \\n[rst2man-indent1]
  16. \\n[rst2man-indent2]
  17. ..
  18. .de1 INDENT
  19. .\" .rstReportMargin pre:
  20. . RS \\$1
  21. . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
  22. . nr rst2man-indent-level +1
  23. .\" .rstReportMargin post:
  24. ..
  25. .de UNINDENT
  26. . RE
  27. .\" indent \\n[an-margin]
  28. .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
  29. .nr rst2man-indent-level -1
  30. .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
  31. .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
  32. ..
  33. .SH SYNOPSIS
  34. .sp
  35. \fBrec_control\fP [\fIOPTION\fP]... \fICOMMAND\fP [\fICOMMAND\-OPTION\fP]...
  36. .SH DESCRIPTION
  37. .sp
  38. \fBrec_control\fP allows the operator to query and control a running
  39. instance of the PowerDNS Recursor.
  40. .sp
  41. \fBrec_control\fP talks to the recursor via a the \(aqcontrolsocket\(aq. Which
  42. is usually located in \fB/var/run\fP . The \fI\-\-socket\-dir\fP or the \fI\-\-config\-dir\fP
  43. and \fI\-\-config\-name\fP switches control to which process \fBrec_control\fP
  44. connects.
  45. .SH EXAMPLES
  46. .sp
  47. To see if the Recursor is alive, run:
  48. .INDENT 0.0
  49. .INDENT 3.5
  50. .sp
  51. .nf
  52. .ft C
  53. # rec_control ping
  54. .ft P
  55. .fi
  56. .UNINDENT
  57. .UNINDENT
  58. .sp
  59. To stop the recursor by hand, run:
  60. .INDENT 0.0
  61. .INDENT 3.5
  62. .sp
  63. .nf
  64. .ft C
  65. # rec_control quit
  66. .ft P
  67. .fi
  68. .UNINDENT
  69. .UNINDENT
  70. .sp
  71. To dump the cache to disk, execute:
  72. .INDENT 0.0
  73. .INDENT 3.5
  74. .sp
  75. .nf
  76. .ft C
  77. # rec_control dump\-cache /tmp/the\-cache
  78. .ft P
  79. .fi
  80. .UNINDENT
  81. .UNINDENT
  82. .SH OPTIONS
  83. .INDENT 0.0
  84. .TP
  85. .B \-\-help
  86. provide this helpful message.
  87. .TP
  88. .BI \-\-config\-dir\fB= <path>
  89. Directory where the recursor.conf lives.
  90. .TP
  91. .BI \-\-config\-name\fB= <name>
  92. Name of the virtual configuration.
  93. .TP
  94. .BI \-\-socket\-dir\fB= <path>
  95. Where the controlsocket will live, please
  96. use \fB\-\-config\-dir\fP instead.
  97. .TP
  98. .BI \-\-socket\-pid\fB= <pid>
  99. When running in SMP mode, pid of \fBpdns_recursor\fP to
  100. control.
  101. .TP
  102. .BI \-\-timeout\fB= <num>
  103. Number of seconds to wait for the remote PowerDNS
  104. Recursor to respond.
  105. .UNINDENT
  106. .SH COMMANDS
  107. .INDENT 0.0
  108. .TP
  109. .B add\-dont\-throttle\-names NAME [NAME...]
  110. Add names for nameserver domains that may not be throttled.
  111. .TP
  112. .B add\-dont\-throttle\-netmasks NETMASK [NETMASK...]
  113. Add netmasks for nameservers that may not be throttled.
  114. .TP
  115. .B add\-nta \fIDOMAIN\fP [\fIREASON\fP]
  116. Add a Negative Trust Anchor for \fIDOMAIN\fP, suffixed optionally with
  117. \fIREASON\fP\&.
  118. .TP
  119. .B add\-ta \fIDOMAIN\fP \fIDSRECORD\fP
  120. Add a Trust Anchor for \fIDOMAIN\fP with DS record data \fIDSRECORD\fP\&. This adds
  121. the new Trust Anchor to the existing set of Trust Anchors for \fIDOMAIN\fP\&.
  122. .TP
  123. .B current\-queries
  124. Shows the currently active queries.
  125. .TP
  126. .B clear\-dont\-throttle\-names NAME [NAME...]
  127. Remove names that are not allowed to be throttled. If \fINAME\fP is \(aq*\(aq, remove all
  128. .TP
  129. .B clear\-dont\-throttle\-netmasks NETMASK [NETMASK...]
  130. Remove netmasks that are not allowed to be throttled. If \fINETMASK\fP is \(aq*\(aq, remove all
  131. .TP
  132. .B clear\-nta \fIDOMAIN\fP\&...
  133. Remove Negative Trust Anchor for one or more \fIDOMAIN\fPs. Set domain to
  134. \(aq*\(aq to remove all NTA\(aqs.
  135. .TP
  136. .B clear\-ta [\fIDOMAIN\fP]...
  137. Remove Trust Anchor for one or more \fIDOMAIN\fPs. Note that removing the
  138. root trust anchor is not possible.
  139. .TP
  140. .B dump\-cache \fIFILENAME\fP
  141. Dumps the entire cache to \fIFILENAME\fP\&. This file should not exist already,
  142. PowerDNS will refuse to overwrite it. While dumping, the recursor will not
  143. answer questions.
  144. .sp
  145. Typical PowerDNS Recursors run multiple threads, therefore you\(aqll see
  146. duplicate, different entries for the same domains. The negative cache is
  147. also dumped to the same file. The per\-thread positive and negative cache
  148. dumps are separated with an appropriate comment.
  149. .sp
  150. \fBNOTE:\fP
  151. .INDENT 7.0
  152. .INDENT 3.5
  153. \fBpdns_recursor\fP often runs in a chroot. You can
  154. retrieve the file using:
  155. .INDENT 0.0
  156. .INDENT 3.5
  157. .sp
  158. .nf
  159. .ft C
  160. rec_control dump\-cache /tmp/file
  161. mv /proc/$(pidof pdns_recursor)/root/tmp/file /tmp/filename
  162. .ft P
  163. .fi
  164. .UNINDENT
  165. .UNINDENT
  166. .UNINDENT
  167. .UNINDENT
  168. .TP
  169. .B dump\-edns \fIFILENAME\fP
  170. Dumps the EDNS status to the filename mentioned. This file should not exist
  171. already, PowerDNS will refuse to overwrite it. While dumping, the recursor
  172. will not answer questions.
  173. .sp
  174. \fBNOTE:\fP
  175. .INDENT 7.0
  176. .INDENT 3.5
  177. \fBpdns_recursor\fP often runs in a chroot. You can
  178. retrieve the file using:
  179. .INDENT 0.0
  180. .INDENT 3.5
  181. .sp
  182. .nf
  183. .ft C
  184. rec_control dump\-edns /tmp/file
  185. mv /proc/$(pidof pdns_recursor)/root/tmp/file /tmp/filename
  186. .ft P
  187. .fi
  188. .UNINDENT
  189. .UNINDENT
  190. .UNINDENT
  191. .UNINDENT
  192. .TP
  193. .B dump\-nsspeeds \fIFILENAME\fP
  194. Dumps the nameserver speed statistics to the \fIFILENAME\fP mentioned. This
  195. file should not exist already, PowerDNS will refuse to overwrite it. While
  196. dumping, the recursor will not answer questions. Statistics are kept per
  197. thread, and the dumps end up in the same file.
  198. .sp
  199. \fBNOTE:\fP
  200. .INDENT 7.0
  201. .INDENT 3.5
  202. \fBpdns_recursor\fP often runs in a chroot. You can
  203. retrieve the file using:
  204. .INDENT 0.0
  205. .INDENT 3.5
  206. .sp
  207. .nf
  208. .ft C
  209. rec_control dump\-nsspeeds /tmp/file
  210. mv /proc/$(pidof pdns_recursor)/root/tmp/file /tmp/filename
  211. .ft P
  212. .fi
  213. .UNINDENT
  214. .UNINDENT
  215. .UNINDENT
  216. .UNINDENT
  217. .TP
  218. .B dump\-rpz \fIZONE NAME\fP \fIFILE NAME\fP
  219. Dumps the content of the RPZ zone named \fIZONE NAME\fP to the \fIFILENAME\fP
  220. mentioned. This file should not exist already, PowerDNS will refuse to
  221. overwrite it otherwise. While dumping, the recursor will not answer
  222. questions.
  223. .sp
  224. \fBNOTE:\fP
  225. .INDENT 7.0
  226. .INDENT 3.5
  227. \fBpdns_recursor\fP often runs in a chroot. You can
  228. retrieve the file using:
  229. .INDENT 0.0
  230. .INDENT 3.5
  231. .sp
  232. .nf
  233. .ft C
  234. rec_control dump\-rpz ZONE_NAME /tmp/file
  235. mv /proc/$(pidof pdns_recursor)/root/tmp/file /tmp/filename
  236. .ft P
  237. .fi
  238. .UNINDENT
  239. .UNINDENT
  240. .UNINDENT
  241. .UNINDENT
  242. .TP
  243. .B dump\-throttlemap \fIFILENAME\fP
  244. Dump the contents of the throttle map to the \fIFILENAME\fP mentioned.
  245. This file should not exist already, PowerDNS will refuse to
  246. overwrite it otherwise. While dumping, the recursor will not answer
  247. questions.
  248. .sp
  249. \fBNOTE:\fP
  250. .INDENT 7.0
  251. .INDENT 3.5
  252. \fBpdns_recursor\fP often runs in a chroot. You can
  253. retrieve the file using:
  254. .INDENT 0.0
  255. .INDENT 3.5
  256. .sp
  257. .nf
  258. .ft C
  259. rec_control dump\-throttlemap /tmp/file
  260. mv /proc/$(pidof pdns_recursor)/root/tmp/file /tmp/filename
  261. .ft P
  262. .fi
  263. .UNINDENT
  264. .UNINDENT
  265. .UNINDENT
  266. .UNINDENT
  267. .TP
  268. .B dump\-failedservers \fIFILENAME\fP
  269. Dump the contents of the failed server map to the \fIFILENAME\fP mentioned.
  270. This file should not exist already, PowerDNS will refuse to
  271. overwrite it otherwise. While dumping, the recursor will not answer
  272. questions.
  273. .sp
  274. \fBNOTE:\fP
  275. .INDENT 7.0
  276. .INDENT 3.5
  277. \fBpdns_recursor\fP often runs in a chroot. You can
  278. retrieve the file using:
  279. .INDENT 0.0
  280. .INDENT 3.5
  281. .sp
  282. .nf
  283. .ft C
  284. rec_control dump\-failedservers /tmp/file
  285. mv /proc/$(pidof pdns_recursor)/root/tmp/file /tmp/filename
  286. .ft P
  287. .fi
  288. .UNINDENT
  289. .UNINDENT
  290. .UNINDENT
  291. .UNINDENT
  292. .TP
  293. .B get \fISTATISTIC\fP [\fISTATISTIC\fP]...
  294. Retrieve a statistic. For items that can be queried, see
  295. \&../metrics
  296. .TP
  297. .B get\-all
  298. Retrieve all known statistics.
  299. .TP
  300. .B get\-dont\-throttle\-names
  301. Get the list of names that are not allowed to be throttled.
  302. .TP
  303. .B get\-dont\-throttle\-netmasks
  304. Get the list of netmasks that are not allowed to be throttled.
  305. .TP
  306. .B get\-ntas
  307. Get a list of the currently configured Negative Trust Anchors.
  308. .TP
  309. .B get\-tas
  310. Get a list of the currently configured Trust Anchors.
  311. .TP
  312. .B get\-parameter \fIKEY\fP [\fIKEY\fP]...
  313. Retrieves the specified configuration parameter(s).
  314. .TP
  315. .B get\-qtypelist
  316. Retrieves QType statistics. Queries from cache aren\(aqt being counted yet.
  317. .TP
  318. .B help
  319. Shows a list of supported commands understood by the running
  320. \fBpdns_recursor\fP
  321. .TP
  322. .B ping
  323. Check if server is alive.
  324. .TP
  325. .B quit
  326. Request shutdown of the recursor, exiting the process while
  327. letting the OS clean up resources.
  328. .TP
  329. .B quit\-nicely
  330. Request nice shutdown of the recursor. This method allows all
  331. threads to finish their current work and releases resources before
  332. exiting. This is the preferred method to stop the recursor.
  333. .TP
  334. .B reload\-acls
  335. Reloads ACLs.
  336. .TP
  337. .B reload\-lua\-script [\fIFILENAME\fP]
  338. (Re)loads Lua script \fIFILENAME\fP\&. If \fIFILENAME\fP is empty, attempt to reload
  339. the currently loaded script. This replaces the script currently loaded.
  340. .TP
  341. .B reload\-lua\-config [\fIFILENAME\fP]
  342. (Re)loads Lua configuration \fIFILENAME\fP\&. If \fIFILENAME\fP is empty, attempt
  343. to reload the currently loaded file. Note that \fIFILENAME\fP will be fully
  344. executed, any settings changed at runtime that are not modified in this
  345. file, will still be active. Reloading RPZ, especially by AXFR, can take
  346. some time; during which the recursor will not answer questions.
  347. .TP
  348. .B reload\-zones
  349. Reload authoritative and forward zones. Retains current configuration in
  350. case of errors.
  351. .TP
  352. .B set\-carbon\-server \fICARBON SERVER\fP [\fICARBON OURNAME\fP]
  353. Set the carbon\-server setting to \fICARBON SERVER\fP\&. If \fICARBON OURNAME\fP is
  354. not empty, also set the carbon\-ourname setting to \fICARBON OURNAME\fP\&.
  355. .TP
  356. .B set\-dnssec\-log\-bogus \fISETTING\fP
  357. Set dnssec\-log\-bogus setting to \fISETTING\fP\&. Set to \(aqon\(aq or \(aqyes\(aq to log
  358. DNSSEC validation failures and to \(aqno\(aq or \(aqoff\(aq to disable logging these
  359. failures.
  360. .TP
  361. .B set\-ecs\-minimum\-ttl \fINUM\fP
  362. Set ecs\-minimum\-ttl\-override to \fINUM\fP\&.
  363. .TP
  364. .B set\-max\-cache\-entries \fINUM\fP
  365. Change the maximum number of entries in the DNS cache. If reduced, the
  366. cache size will start shrinking to this number as part of the normal
  367. cache purging process, which might take a while.
  368. .TP
  369. .B set\-max\-packetcache\-entries \fINUM\fP
  370. Change the maximum number of entries in the packet cache. If reduced, the
  371. cache size will start shrinking to this number as part of the normal
  372. cache purging process, which might take a while.
  373. .TP
  374. .B set\-minimum\-ttl \fINUM\fP
  375. Set minimum\-ttl\-override to \fINUM\fP\&.
  376. .TP
  377. .B top\-queries
  378. Shows the top\-20 queries. Statistics are over the last
  379. \(aqstats\-ringbuffer\-entries\(aq queries.
  380. .TP
  381. .B top\-pub\-queries
  382. Shows the top\-20 queries grouped by public suffix list. Statistics are over
  383. the last \(aqstats\-ringbuffer\-entries\(aq queries.
  384. .TP
  385. .B top\-largeanswer\-remotes
  386. Shows the top\-20 remote hosts causing large answers. Statistics are over
  387. the last \(aqstats\-ringbuffer\-entries\(aq queries.
  388. .TP
  389. .B top\-remotes
  390. Shows the top\-20 most active remote hosts. Statistics are over the last
  391. \(aqstats\-ringbuffer\-entries\(aq queries.
  392. .TP
  393. .B top\-servfail\-queries
  394. Shows the top\-20 queries causing servfail responses. Statistics are over
  395. the last \(aqstats\-ringbuffer\-entries\(aq queries.
  396. .TP
  397. .B top\-bogus\-queries
  398. Shows the top\-20 queries causing bogus responses. Statistics are over
  399. the last \(aqstats\-ringbuffer\-entries\(aq queries.
  400. .TP
  401. .B top\-pub\-servfail\-queries
  402. Shows the top\-20 queries causing servfail responses grouped by public
  403. suffix list. Statistics are over the last \(aqstats\-ringbuffer\-entries\(aq
  404. queries.
  405. .TP
  406. .B top\-pub\-bogus\-queries
  407. Shows the top\-20 queries causing bogus responses grouped by public
  408. suffix list. Statistics are over the last \(aqstats\-ringbuffer\-entries\(aq
  409. queries.
  410. .TP
  411. .B top\-servfail\-remotes
  412. Shows the top\-20 most active remote hosts causing servfail responses.
  413. Statistics are over the last \(aqstats\-ringbuffer\-entries\(aq queries.
  414. .TP
  415. .B top\-bogus\-remotes
  416. Shows the top\-20 most active remote hosts causing bogus responses.
  417. Statistics are over the last \(aqstats\-ringbuffer\-entries\(aq queries.
  418. .TP
  419. .B top\-timeouts
  420. Shows the top\-20 most active downstream timeout destinations.
  421. Statistics are over the last \(aqstats\-ringbuffer\-entries\(aq queries.
  422. .TP
  423. .B trace\-regex \fIREGEX\fP
  424. Emit resolution trace for matching queries. Empty regex to disable trace.
  425. .sp
  426. Queries matching this regular expression will generate voluminous tracing
  427. output. Be aware that matches from the packet cache will still not generate
  428. tracing. To unset the regex, pass \fBtrace\-regex\fP without a new regex.
  429. .sp
  430. The regular expression is matched against domain queries terminated with a
  431. dot. For example the regex \fB\(aqpowerdns.com$\(aq\fP will not match a query for
  432. \fB\(aqwww.powerdns.com\(aq\fP, since the attempted match will be with
  433. \fB\(aqwww.powerdns.com.\(aq\fP\&.
  434. .sp
  435. In addition, since this is a regular expression, to exclusively match
  436. queries for \fB\(aqwww.powerdns.com\(aq\fP, one should escape the dots:
  437. \fB\(aq^www\e.powerdns\e.com\e.$\(aq\fP\&.
  438. Note that the single quotes prevent
  439. further interpretation of the backslashes by the shell.
  440. .sp
  441. Multiple matches can be chained with the \fB|\fP operator. For example, to
  442. match all queries for Dutch (\fB\&.nl\fP) and German (\fB\&.de\fP) domain names, use:
  443. \fB\(aq\e.nl\e.$|\e.de\e.$\(aq\fP\&.
  444. .TP
  445. .B unload\-lua\-script
  446. Unloads Lua script if one was loaded.
  447. .TP
  448. .B version
  449. Report running version.
  450. .TP
  451. .B wipe\-cache \fIDOMAIN\fP [\fIDOMAIN\fP] [...]
  452. Wipe entries for \fIDOMAIN\fP (exact name match) from the cache. This is useful
  453. if, for example, an important server has a new IP address, but the TTL has
  454. not yet expired. Multiple domain names can be passed.
  455. \fIDOMAIN\fP can be suffixed with a \(aq$\(aq. to delete the whole tree from the
  456. cache. i.e. \(aqpowerdns.com$\(aq will remove all cached entries under and
  457. including the powerdns.com name.
  458. .sp
  459. \fBNote\fP: this command also wipes the negative cache.
  460. .sp
  461. \fBWarning\fP: Don\(aqt just wipe "www.somedomain.com", its NS records or CNAME
  462. target may still be undesired, so wipe "somedomain.com" as well.
  463. .TP
  464. .B wipe\-cache\-typed \fIqtype\fP \fIDOMAIN\fP [\fIDOMAIN\fP] [...]
  465. Same as wipe\-cache, but only wipe records of type \fIqtype\fP\&.
  466. .UNINDENT
  467. .SH SEE ALSO
  468. .sp
  469. \fBpdns_recursor(1)\fP
  470. .SH AUTHOR
  471. PowerDNS.COM BV
  472. .SH COPYRIGHT
  473. 2001-2019, PowerDNS.COM BV
  474. .\" Generated by docutils manpage writer.
  475. .