docs/settings.rst

   1 Authoritative Server Settings
   2 =============================
   3
   4 All PowerDNS Authoritative Server settings are listed here, excluding
   5 those that originate from backends, which are documented in the relevant
   6 chapters. These settings can be set inside ``pdns.conf`` or on the
   7 commandline when invoking the ``pdns`` binary.
   8
   9 You can use ``+=`` syntax to set some variables incrementally, but this
  10 requires you to have at least one non-incremental setting for the
  11 variable to act as base setting. This is mostly useful for
  12 :ref:`setting-include-dir` directive.
  13
  14 For boolean settings, specifying the name of the setting without a value
  15 means ``yes``.
  16
  17 .. _setting-8bit-dns:
  18
  19 ``8bit-dns``
  20 ------------
  21
  22 -  Allow 8 bit dns queries
  23 -  Default: no
  24
  25 .. versionadded:: 4.0.0
  26
  27 Allow 8 bit DNS queries.
  28
  29 .. _setting-allow-axfr-ips:
  30
  31 ``allow-axfr-ips``
  32 ------------------
  33
  34 -  IP ranges, separated by commas
  35 -  Default: 127.0.0.0/8,::1
  36
  37 If set, only these IP addresses or netmasks will be able to perform
  38 AXFR.
  39
  40 .. _setting-allow-dnsupdate-from:
  41
  42 ``allow-dnsupdate-from``
  43 ------------------------
  44
  45 -  IP ranges, separated by commas
  46 -  Default: 127.0.0.0/8,::1
  47
  48 Allow DNS updates from these IP ranges. Set to empty string to honour ``ALLOW-DNSUPDATE-FROM`` in :ref:`metadata-allow-dnsupdate-from`.
  49
  50 .. _setting-allow-notify-from:
  51
  52 ``allow-notify-from``
  53 ---------------------
  54
  55 -  IP ranges, separated by commas
  56 -  Default: 0.0.0.0/0,::/0
  57
  58 Allow AXFR NOTIFY from these IP ranges. Setting this to an empty string
  59 will drop all incoming notifies.
  60
  61 .. _setting-allow-unsigned-notify:
  62
  63 ``allow-unsigned-notify``
  64 -------------------------
  65
  66 -  Boolean
  67 -  Default: yes
  68
  69 .. versionadded:: 4.0.0
  70
  71 Turning this off requires all notifications that are received to be
  72 signed by valid TSIG signature for the zone.
  73
  74 .. _setting-allow-unsigned-supermaster:
  75
  76 ``allow-unsigned-supermaster``
  77 ------------------------------
  78
  79 -  Boolean
  80 -  Default: yes
  81
  82 .. versionadded:: 4.0.0
  83
  84 Turning this off requires all supermaster notifications to be signed by
  85 valid TSIG signature. It will accept any existing key on slave.
  86
  87 .. _setting-allow-recursion:
  88
  89 ``allow-recursion``
  90 -------------------
  91
  92 -  IP ranges, separated by commas
  93 -  Default: 0.0.0.0/0
  94 -  Removed in: 4.1.0
  95
  96 By specifying ``allow-recursion``, recursion can be restricted to
  97 netmasks specified. The default is to allow recursion from everywhere.
  98 Example: ``allow-recursion=198.51.100.0/24, 10.0.0.0/8, 192.0.2.4``.
  99
 100 .. _setting-also-notify:
 101
 102 ``also-notify``
 103 ---------------
 104
 105 -  IP addresses, separated by commas
 106
 107 When notifying a domain, also notify these nameservers. Example:
 108 ``also-notify=192.0.2.1, 203.0.113.167``. The IP addresses listed in
 109 ``also-notify`` always receive a notification. Even if they do not match
 110 the list in :ref:`setting-only-notify`.
 111
 112 .. _setting-any-to-tcp:
 113
 114 ``any-to-tcp``
 115 --------------
 116
 117 -  Boolean
 118 -  Default: yes
 119
 120 .. versionchanged:: 4.0.1, was 'no' before.
 121
 122 Answer questions for the ANY on UDP with a truncated packet that refers
 123 the remote server to TCP. Useful for mitigating reflection attacks.
 124
 125 .. _setting-api:
 126
 127 ``api``
 128 -------
 129
 130 -  Boolean
 131 -  Default: no
 132
 133 Enable/disable the :doc:`http-api/index`.
 134
 135 .. _setting-api-key:
 136
 137 ``api-key``
 138 -----------
 139
 140 -  String
 141
 142 .. versionadded:: 4.0.0
 143
 144 Static pre-shared authentication key for access to the REST API.
 145
 146 .. _setting-api-readonly:
 147
 148 ``api-readonly``
 149 ----------------
 150
 151 -  Boolean
 152 -  Default: no
 153
 154 .. versionadded:: 4.0.0
 155
 156 Disallow data modification through the REST API when set.
 157
 158 .. _setting-axfr-lower-serial:
 159
 160 ``axfr-lower-serial``
 161 ---------------------
 162
 163 -  Boolean
 164 -  Default: no
 165
 166 .. versionadded:: 4.0.4
 167
 168 Also AXFR a zone from a master with a lower serial.
 169
 170 .. _setting-cache-ttl:
 171
 172 ``cache-ttl``
 173 -------------
 174
 175 -  Integer
 176 -  Default: 20
 177
 178 Seconds to store packets in the :ref:`packet-cache`.
 179
 180 .. _setting-carbon-namespace:
 181
 182 ``carbon-namespace``
 183 --------------------
 184
 185 -  String
 186 -  Default: pdns
 187
 188 .. versionadded:: 4.2.0
 189
 190 Set the namespace or first string of the metric key. Be careful not to include
 191 any dots in this setting, unless you know what you are doing.
 192 See :ref:`metricscarbon`
 193
 194 .. _setting-carbon-ourname:
 195
 196 ``carbon-ourname``
 197 ------------------
 198
 199 -  String
 200 -  Default: the hostname of the server
 201
 202 If sending carbon updates, if set, this will override our hostname. Be
 203 careful not to include any dots in this setting, unless you know what
 204 you are doing. See :ref:`metricscarbon`
 205
 206 .. _setting-carbon-instance:
 207
 208 ``carbon-instance``
 209 -------------------
 210
 211 -  String
 212 -  Default: auth
 213
 214 .. versionadded:: 4.2.0
 215
 216 Set the instance or third string of the metric key. Be careful not to include
 217 any dots in this setting, unless you know what you are doing.
 218 See :ref:`metricscarbon`
 219
 220 .. _setting-carbon-server:
 221
 222 ``carbon-server``
 223 -----------------
 224
 225 -  IP Address
 226
 227 Send all available metrics to this server via the carbon protocol, which
 228 is used by graphite and metronome. It has to be an address (no
 229 hostnames). You may specify an alternate port by appending :port, ex:
 230 127.0.0.1:2004. See :ref:`metricscarbon`.
 231
 232 .. _setting-carbon-interval:
 233
 234 ``carbon-interval``
 235 -------------------
 236
 237 -  Integer
 238 -  Default: 30
 239
 240 If sending carbon updates, this is the interval between them in seconds.
 241 See :ref:`metricscarbon`.
 242
 243 .. _setting-chroot:
 244
 245 ``chroot``
 246 ----------
 247
 248 -  Path
 249
 250 If set, chroot to this directory for more security. See :doc:`security`.
 251
 252 Make sure that ``/dev/log`` is available from within the chroot. Logging
 253 will silently fail over time otherwise (on logrotate).
 254
 255 When setting ``chroot``, all other paths in the config (except for
 256 :ref:`setting-config-dir` and :ref:`setting-module-dir`)
 257 set in the configuration are relative to the new root.
 258
 259 When running on a system where systemd manages services, ``chroot`` does
 260 not work out of the box, as PowerDNS cannot use the ``NOTIFY_SOCKET``.
 261 Either don't ``chroot`` on these systems or set the 'Type' of the this
 262 service to 'simple' instead of 'notify' (refer to the systemd
 263 documentation on how to modify unit-files)
 264
 265 .. _setting-config-dir:
 266
 267 ``config-dir``
 268 --------------
 269
 270 -  Path
 271
 272 Location of configuration directory (``pdns.conf``). Usually
 273 ``/etc/powerdns``, but this depends on ``SYSCONFDIR`` during
 274 compile-time.
 275
 276 .. _setting-config-name:
 277
 278 ``config-name``
 279 ---------------
 280
 281 -  String
 282
 283 Name of this virtual configuration - will rename the binary image. See
 284 :doc:`guides/virtual-instances`.
 285
 286 .. _setting-control-console:
 287
 288 ``control-console``
 289 -------------------
 290
 291 Debugging switch - don't use.
 292
 293 .. _setting-daemon:
 294
 295 ``daemon``
 296 ----------
 297
 298 -  Boolean
 299 -  Default: no
 300
 301 Operate as a daemon.
 302
 303 .. _setting-default-api-rectify:
 304
 305 ``default-api-rectify``
 306 -----------------------
 307 -  Boolean
 308 -  Default: yes
 309
 310 .. versionadded:: 4.2.0
 311
 312 The value of :ref:`metadata-api-rectify` if it is not set on the zone.
 313
 314 .. note::
 315   Pre 4.2.0 the default was always no.
 316
 317 .. _setting-default-ksk-algorithms:
 318 .. _setting-default-ksk-algorithm:
 319
 320 ``default-ksk-algorithm``
 321 --------------------------
 322
 323 -  String
 324 -  Default: ecdsa256
 325
 326 .. versionchanged:: 4.1.0
 327   Renamed from ``default-ksk-algorithms``. No longer supports multiple algorithm names.
 328
 329 The algorithm that should be used for the KSK when running
 330 :doc:`pdnsutil secure-zone <manpages/pdnsutil.1>` or using the :doc:`Zone API endpoint <http-api/cryptokey>`
 331 to enable DNSSEC. Must be one of:
 332
 333 * rsasha1
 334 * rsasha256
 335 * rsasha512
 336 * ecdsa256 (ECDSA P-256 with SHA256)
 337 * ecdsa384 (ECDSA P-384 with SHA384)
 338 * ed25519
 339 * ed448
 340
 341 .. note::
 342   Actual supported algorithms depend on the crypto-libraries
 343   PowerDNS was compiled against. To check the supported DNSSEC algoritms
 344   in your build of PowerDNS, run ``pdnsutil list-algorithms``.
 345
 346 .. _setting-default-ksk-size:
 347
 348 ``default-ksk-size``
 349 --------------------
 350
 351 -  Integer
 352 -  Default: whichever is default for `default-ksk-algorithm`_
 353
 354 The default keysize for the KSK generated with :doc:`pdnsutil secure-zone <dnssec/pdnsutil>`.
 355 Only relevant for algorithms with non-fixed keysizes (like RSA).
 356
 357 .. _setting-default-soa-name:
 358
 359 ``default-soa-name``
 360 --------------------
 361
 362 -  String
 363 -  Default: a.misconfigured.powerdns.server
 364
 365 Name to insert in the SOA record if none set in the backend.
 366
 367 .. _setting-default-soa-edit:
 368
 369 ``default-soa-edit``
 370 --------------------
 371
 372 -  String
 373 -  Default: empty
 374
 375 Use this soa-edit value for all zones if no
 376 :ref:`metadata-soa-edit` metadata value is set.
 377
 378 .. _setting-default-soa-edit-signed:
 379
 380 ``default-soa-edit-signed``
 381 ---------------------------
 382
 383 -  String
 384 -  Default: empty
 385
 386 Use this soa-edit value for all signed zones if no
 387 :ref:`metadata-soa-edit` metadata value is set.
 388 Overrides :ref:`setting-default-soa-edit`
 389
 390 .. _setting-default-soa-mail:
 391
 392 ``default-soa-mail``
 393 --------------------
 394
 395 -  String
 396
 397 Mail address to insert in the SOA record if none set in the backend.
 398
 399 .. _setting-default-ttl:
 400
 401 ``default-ttl``
 402 ---------------
 403
 404 -  Integer
 405 -  Default: 3600
 406
 407 TTL to use when none is provided.
 408
 409 .. _setting-default-zsk-algorithms:
 410 .. _setting-default-zsk-algorithm:
 411
 412 ``default-zsk-algorithm``
 413 --------------------------
 414
 415 -  String
 416 -  Default: (empty)
 417
 418 .. versionchanged:: 4.1.0
 419   Renamed from ``default-zsk-algorithms``. Does no longer support multiple algorithm names.
 420
 421 The algorithm that should be used for the ZSK when running
 422 :doc:`pdnsutil secure-zone <manpages/pdnsutil.1>` or using the :doc:`Zone API endpoint <http-api/cryptokey>`
 423 to enable DNSSEC. Must be one of:
 424
 425 * rsasha1
 426 * rsasha256
 427 * rsasha512
 428 * ecdsa256 (ECDSA P-256 with SHA256)
 429 * ecdsa384 (ECDSA P-384 with SHA384)
 430 * ed25519
 431 * ed448
 432
 433 .. note::
 434   Actual supported algorithms depend on the crypto-libraries
 435   PowerDNS was compiled against. To check the supported DNSSEC algoritms
 436   in your build of PowerDNS, run ``pdnsutil list-algorithms``.
 437
 438 .. _setting-default-zsk-size:
 439
 440 ``default-zsk-size``
 441 --------------------
 442
 443 -  Integer
 444 -  Default: 0 (automatic default for `default-zsk-algorithm`_)
 445
 446 The default keysize for the ZSK generated with :doc:`pdnsutil secure-zone <dnssec/pdnsutil>`.
 447 Only relevant for algorithms with non-fixed keysizes (like RSA).
 448
 449 .. _setting-direct-dnskey:
 450
 451 ``direct-dnskey``
 452 -----------------
 453
 454 -  Boolean
 455 -  Default: no
 456
 457 Read additional DNSKEY, CDS and CDNSKEY records from the records table/your BIND zonefile. If not
 458 set, DNSKEY, CDS and CDNSKEY records in the zonefiles are ignored.
 459
 460 .. _setting-disable-axfr:
 461
 462 ``disable-axfr``
 463 ----------------
 464
 465 -  Boolean
 466 -  Default: no
 467
 468 Do not allow zone transfers.
 469
 470 .. _setting-disable-axfr-rectify:
 471
 472 ``disable-axfr-rectify``
 473 ------------------------
 474
 475 -  Boolean
 476 -  Default: no
 477
 478 Disable the rectify step during an outgoing AXFR. Only required for
 479 regression testing.
 480
 481 .. _setting-disable-syslog:
 482
 483 ``disable-syslog``
 484 ------------------
 485
 486 -  Boolean
 487 -  Default: no
 488
 489 Do not log to syslog, only to stdout. Use this setting when running
 490 inside a supervisor that handles logging (like systemd).
 491
 492 .. warning::
 493   Do not use this setting in combination with :ref:`setting-daemon` as all
 494   logging will disappear.
 495
 496 .. _setting-disable-tcp:
 497
 498 ``disable-tcp``
 499 ---------------
 500
 501 -  Boolean
 502 -  Default: no
 503
 504 Do not listen to TCP queries. Breaks RFC compliance.
 505
 506 .. _setting-distributor-threads:
 507
 508 ``distributor-threads``
 509 -----------------------
 510
 511 -  Integer
 512 -  Default: 3
 513
 514 Number of Distributor (backend) threads to start per receiver thread.
 515 See :doc:`performance`.
 516
 517 .. _setting-dname-processing:
 518
 519 ``dname-processing``
 520 --------------------
 521
 522 -  Boolean
 523 -  Default: no
 524
 525 Synthesise CNAME records from DNAME records as required. This
 526 approximately doubles query load. **Do not combine with DNSSEC!**
 527
 528 .. _setting-dnssec-key-cache-ttl:
 529
 530 ``dnssec-key-cache-ttl``
 531 ------------------------
 532
 533 -  Integer
 534 -  Default: 30
 535
 536 Seconds to cache DNSSEC keys from the database. A value of 0 disables
 537 caching.
 538
 539 .. _setting-dnsupdate:
 540
 541 ``dnsupdate``
 542 -------------
 543
 544 -  Boolean
 545 -  Default: no
 546
 547 Enable/Disable DNS update (RFC2136) support. See :doc:`dnsupdate` for more.
 548
 549 .. _setting-do-ipv6-additional-processing:
 550
 551 ``do-ipv6-additional-processing``
 552 ---------------------------------
 553
 554 -  Boolean
 555 -  Default: yes
 556
 557 Perform AAAA additional processing. This sends AAAA records in the
 558 ADDITIONAL section when sending a referral.
 559
 560 .. _setting-domain-metadata-cache-ttl:
 561
 562 ``domain-metadata-cache-ttl``
 563 -----------------------------
 564
 565 -  Integer
 566 -  Default: 60
 567
 568 Seconds to cache domain metadata from the database. A value of 0
 569 disables caching.
 570
 571 .. _setting-edns-subnet-processing:
 572
 573 ``edns-subnet-processing``
 574 --------------------------
 575
 576 -  Boolean
 577 -  Default: no
 578
 579 Enables EDNS subnet processing, for backends that support it.
 580
 581 .. _setting-enable-lua-records:
 582
 583 ``enable-lua-records``
 584 ----------------------
 585
 586 -  Boolean
 587 -  Default: no
 588
 589 Enable globally the LUA records feature
 590
 591 .. _setting-entropy-source:
 592
 593 ``entropy-source``
 594 ------------------
 595
 596 -  Path
 597 -  Default: /dev/urandom
 598
 599 Entropy source file to use.
 600
 601 .. _setting-expand-alias:
 602
 603 ``expand-alias``
 604 ----------------
 605
 606 -  Boolean
 607 -  Default: no
 608 -  Since: 4.1.0
 609
 610 If this is enabled, ALIAS records are expanded (synthesised to their
 611 A/AAAA).
 612
 613 If this is disabled (the default), ALIAS records will not expanded and
 614 the server will will return NODATA for A/AAAA queries for such names.
 615
 616 **note**: :ref:`setting-resolver` must also be set for ALIAS
 617 expansion to work!
 618
 619 **note**: In PowerDNS Authoritative Server 4.0.x, this setting did not
 620 exist and ALIAS was always expanded.
 621
 622 .. _setting-forward-dnsupdate:
 623
 624 ``forward-dnsupdate``
 625 ---------------------
 626
 627 -  Boolean
 628 -  Default: no
 629
 630 Forward DNS updates sent to a slave to the master.
 631
 632 .. _setting-forward-notify:
 633
 634 ``forward-notify``
 635 ------------------
 636
 637 -  IP addresses, separated by commas
 638
 639 IP addresses to forward received notifications to regardless of master
 640 or slave settings.
 641
 642 .. note::
 643   The intended use is in anycast environments where it might be
 644   necessary for a proxy server to perform the AXFR. The usual checks are
 645   performed before any received notification is forwarded.
 646
 647 .. _setting-guardian:
 648
 649 ``guardian``
 650 ------------
 651
 652 -  Boolean
 653 -  Default: no
 654
 655 Run within a guardian process. See :ref:`running-guardian`.
 656
 657 .. _setting-include-dir:
 658
 659 ``include-dir``
 660 ---------------
 661
 662 -  Path
 663
 664 Directory to scan for additional config files. All files that end with
 665 .conf are loaded in order using ``POSIX`` as locale.
 666
 667 .. _setting-launch:
 668
 669 ``launch``
 670 ----------
 671
 672 -  Backend names, separated by commas
 673
 674 Which backends to launch and order to query them in. Launches backends.
 675 In its most simple form, supply all backends that need to be launched.
 676 e.g.
 677
 678 ::
 679
 680     launch=bind,gmysql,remote
 681
 682 If you find that you need to query a backend multiple times with
 683 different configuration, you can specify a name for later
 684 instantiations. e.g.:
 685
 686 ::
 687
 688     launch=gmysql,gmysql:server2
 689
 690 In this case, there are 2 instances of the gmysql backend, one by the
 691 normal name and the second one is called 'server2'. The backend
 692 configuration item names change: e.g. ``gmysql-host`` is available to
 693 configure the ``host`` setting of the first or main instance, and
 694 ``gmysql-server2-host`` for the second one.
 695
 696 Running multiple instances of the bind backend is not allowed.
 697
 698 .. _setting-load-modules:
 699
 700 ``load-modules``
 701 ----------------
 702
 703 -  Paths, separated by commas
 704
 705 If backends are available in nonstandard directories, specify their
 706 location here. Multiple files can be loaded if separated by commas. Only
 707 available in non-static distributions.
 708
 709 .. _setting-local-address:
 710
 711 ``local-address``
 712 -----------------
 713
 714 -  IPv4 Addresses, separated by commas or whitespace
 715 -  Default: 0.0.0.0
 716
 717 Local IP address to which we bind. It is highly advised to bind to
 718 specific interfaces and not use the default 'bind to any'. This causes
 719 big problems if you have multiple IP addresses. Unix does not provide a
 720 way of figuring out what IP address a packet was sent to when binding to
 721 any.
 722
 723 .. _setting-log-timestamp:
 724
 725 ``log-timestamp``
 726 -----------------
 727
 728 .. versionadded:: 4.1.0
 729
 730 - Bool
 731 - Default: yes
 732
 733 When printing log lines to stdout, prefix them with timestamps.
 734 Disable this if the process supervisor timestamps these lines already.
 735
 736 .. note::
 737   The systemd unit file supplied with the source code already disables timestamp printing
 738
 739 .. _setting-lua-records-exec-limit:
 740
 741 ``lua-records-exec-limit``
 742 -----------------------------
 743
 744 -  Integer
 745 -  Default: 1000
 746
 747 Limit LUA records scripts to ``lua-records-exec-limit`` instructions.
 748 Setting this to any value less than or equal to 0 will set no limit.
 749
 750 .. _setting-non-local-bind:
 751
 752 ``non-local-bind``
 753 ------------------
 754
 755 -  Boolean
 756 -  Default: no
 757
 758 Bind to addresses even if one or more of the
 759 :ref:`setting-local-address`'s do not exist on this server.
 760 Setting this option will enable the needed socket options to allow
 761 binding to non-local addresses. This feature is intended to facilitate
 762 ip-failover setups, but it may also mask configuration issues and for
 763 this reason it is disabled by default.
 764
 765 .. _setting-lua-axfr-script:
 766
 767 ``lua-axfr-script``
 768 -------------------
 769
 770 -  String
 771 -  Default: empty
 772
 773 .. versionadded:: 4.1.0
 774
 775 Script to be used to edit incoming AXFRs, see :ref:`modes-of-operation-axfrfilter`
 776
 777 .. _setting-local-address-nonexist-fail:
 778
 779 ``local-address-nonexist-fail``
 780 -------------------------------
 781
 782 -  Boolean
 783 -  Default: no
 784
 785 Fail to start if one or more of the
 786 :ref:`setting-local-address`'s do not exist on this server.
 787
 788 .. _setting-local-ipv6:
 789
 790 ``local-ipv6``
 791 --------------
 792
 793 -  IPv6 Addresses, separated by commas or whitespace
 794 -  Default: '::'
 795
 796 Local IPv6 address to which we bind. It is highly advised to bind to
 797 specific interfaces and not use the default 'bind to any'. This causes
 798 big problems if you have multiple IP addresses.
 799
 800 .. _setting-local-ipv6-nonexist-fail:
 801
 802 ``local-ipv6-nonexist-fail``
 803 ----------------------------
 804
 805 -  Boolean
 806 -  Default: no
 807
 808 Fail to start if one or more of the :ref:`setting-local-ipv6`
 809 addresses do not exist on this server.
 810
 811 .. _setting-local-port:
 812
 813 ``local-port``
 814 --------------
 815
 816 -  Integer
 817 -  Default: 53
 818
 819 The port on which we listen. Only one port possible.
 820
 821 .. _setting-log-dns-details:
 822
 823 ``log-dns-details``
 824 -------------------
 825
 826 -  Boolean
 827 -  Default: no
 828
 829 If set to 'no', informative-only DNS details will not even be sent to
 830 syslog, improving performance.
 831
 832 .. _setting-logging-facility:
 833
 834 ``logging-facility``
 835 --------------------
 836
 837 If set to a digit, logging is performed under this LOCAL facility. See :ref:`logging-to-syslog`.
 838 Do not pass names like 'local0'!
 839
 840 .. _setting-loglevel:
 841
 842 ``loglevel``
 843 ------------
 844
 845 -  Integer
 846 -  Default: 4
 847
 848 Amount of logging. Higher is more. Do not set below 3. Corresponds to "syslog" level values,
 849 e.g. error = 3, warning = 4, notice = 5, info = 6
 850
 851 .. _setting-log-dns-queries:
 852
 853 ``log-dns-queries``
 854 -------------------
 855
 856 -  Boolean
 857 -  Default: no
 858
 859 Tell PowerDNS to log all incoming DNS queries. This will lead to a lot
 860 of logging! Only enable for debugging! Set :ref:`setting-loglevel`
 861 to at least 5 to see the logs.
 862
 863 .. _setting-lua-prequery-script:
 864
 865 ``lua-prequery-script``
 866 -----------------------
 867
 868 -  Path
 869
 870 Lua script to run before answering a query. This is a feature used
 871 internally for regression testing. The API of this functionality is not
 872 guaranteed to be stable, and is in fact likely to change.
 873
 874 .. _setting-master:
 875
 876 ``master``
 877 ----------
 878
 879 -  Boolean
 880 -  Default: no
 881
 882 Turn on master support. See :ref:`master-operation`.
 883
 884 .. _setting-max-cache-entries:
 885
 886 ``max-cache-entries``
 887 ---------------------
 888
 889 -  Integer
 890 -  Default: 1000000
 891
 892 Maximum number of entries in the query cache. 1 million (the default)
 893 will generally suffice for most installations. Starting with 4.1, the
 894 packet and query caches are distinct so you might also want to see
 895 ``max-packet-cache-entries``.
 896
 897 .. _setting-max-ent-entries:
 898
 899 ``max-ent-entries``
 900 -------------------
 901
 902 -  Integer
 903 -  Default: 100000
 904
 905 Maximum number of empty non-terminals to add to a zone. This is a
 906 protection measure to avoid database explosion due to long names.
 907
 908 .. _setting-max-nsec3-iterations:
 909
 910 ``max-nsec3-iterations``
 911 ------------------------
 912
 913 -  Integer
 914 -  Default: 500
 915
 916 Limit the number of NSEC3 hash iterations
 917
 918 .. _setting-max-packet-cache-entries:
 919
 920 ``max-packet-cache-entries``
 921 ----------------------------
 922
 923 -  Integer
 924 -  Default: 1000000
 925
 926 Maximum number of entries in the packet cache. 1 million (the default)
 927 will generally suffice for most installations. This setting has been
 928 introduced in 4.1, previous used the ``max-cache-entries`` setting for
 929 both the packet and query caches.
 930
 931 .. _setting-max-queue-length:
 932
 933 ``max-queue-length``
 934 --------------------
 935
 936 -  Integer
 937 -  Default: 5000
 938
 939 If this many packets are waiting for database attention, consider the
 940 situation hopeless and respawn.
 941
 942 .. _setting-max-signature-cache-entries:
 943
 944 ``max-signature-cache-entries``
 945 -------------------------------
 946
 947 -  Integer
 948 -  Default: 2^31-1 (on most systems), 2^63-1 (on ILP64 systems)
 949
 950 Maximum number of signatures cache entries
 951
 952 .. _setting-max-tcp-connection-duration:
 953
 954 ``max-tcp-connection-duration``
 955 -------------------------------
 956
 957 -  Integer
 958 -  Default: 0
 959
 960 Maximum time in seconds that a TCP DNS connection is allowed to stay
 961 open. 0 means unlimited. Note that exchanges related to an AXFR or IXFR
 962 are not affected by this setting.
 963
 964 .. _setting-max-tcp-connections:
 965
 966 ``max-tcp-connections``
 967 -----------------------
 968
 969 -  Integer
 970 -  Default: 20
 971
 972 Allow this many incoming TCP DNS connections simultaneously.
 973
 974 .. _setting-max-tcp-connections-per-client:
 975
 976 ``max-tcp-connections-per-client``
 977 ----------------------------------
 978
 979 -  Integer
 980 -  Default: 0
 981
 982 Maximum number of simultaneous TCP connections per client. 0 means
 983 unlimited.
 984
 985 .. _setting-max-tcp-transactions-per-conn:
 986
 987 ``max-tcp-transactions-per-conn``
 988 ---------------------------------
 989
 990 -  Integer
 991 -  Default: 0
 992
 993 Allow this many DNS queries in a single TCP transaction. 0 means
 994 unlimited. Note that exchanges related to an AXFR or IXFR are not
 995 affected by this setting.
 996
 997 .. _setting-module-dir:
 998
 999 ``module-dir``
1000 --------------
1001
1002 -  Path
1003
1004 Directory for modules. Default depends on ``PKGLIBDIR`` during
1005 compile-time.
1006
1007 .. _setting-negquery-cache-ttl:
1008
1009 ``negquery-cache-ttl``
1010 ----------------------
1011
1012 -  Integer
1013 -  Default: 60
1014
1015 Seconds to store queries with no answer in the Query Cache. See ref:`query-cache`.
1016
1017 .. _setting-no-config:
1018
1019 ``no-config``
1020 -------------
1021
1022 -  Boolean
1023 -  Default: no
1024
1025 Do not attempt to read the configuration file.
1026
1027 .. _setting-no-shuffle:
1028
1029 ``no-shuffle``
1030 --------------
1031
1032 -  Boolean
1033 -  Default: no
1034
1035 Do not attempt to shuffle query results, used for regression testing.
1036
1037 .. _setting-overload-queue-length:
1038
1039 ``overload-queue-length``
1040 -------------------------
1041
1042 -  Integer
1043 -  Default: 0 (disabled)
1044
1045 If this many packets are waiting for database attention, answer any new
1046 questions strictly from the packet cache.
1047
1048 .. _setting-reuseport:
1049
1050 ``reuseport``
1051 -------------
1052
1053 -  Boolean
1054 -  Default: No
1055
1056 On Linux 3.9 and some BSD kernels the ``SO_REUSEPORT`` option allows
1057 each receiver-thread to open a new socket on the same port which allows
1058 for much higher performance on multi-core boxes. Setting this option
1059 will enable use of ``SO_REUSEPORT`` when available and seamlessly fall
1060 back to a single socket when it is not available. A side-effect is that
1061 you can start multiple servers on the same IP/port combination which may
1062 or may not be a good idea. You could use this to enable transparent
1063 restarts, but it may also mask configuration issues and for this reason
1064 it is disabled by default.
1065
1066 .. _setting-rng:
1067
1068 ``rng``
1069 -------
1070
1071 - String
1072 - Default: auto
1073
1074 Specify which random number generator to use. Permissible choises are
1075  - auto - choose automatically
1076  - sodium - Use libsodium ``randombytes_uniform``
1077  - openssl - Use libcrypto ``RAND_bytes``
1078  - getrandom - Use libc getrandom, falls back to urandom if it does not really work
1079  - arc4random - Use BSD ``arc4random_uniform``
1080  - urandom - Use ``/dev/urandom``
1081  - kiss - Use simple settable deterministic RNG. **FOR TESTING PURPOSES ONLY!**
1082
1083 .. note::
1084   Not all choises are available on all systems.
1085
1086 .. _setting-security-poll-suffix:
1087
1088 ``security-poll-suffix``
1089 ------------------------
1090
1091 -  String
1092 -  Default: secpoll.powerdns.com.
1093
1094 Domain name from which to query security update notifications. Setting
1095 this to an empty string disables secpoll.
1096
1097 .. _setting-server-id:
1098
1099 ``server-id``
1100 -------------
1101
1102 -  String
1103 -  Default: The hostname of the server
1104
1105 This is the server ID that will be returned on an EDNS NSID query.
1106
1107 .. _setting-only-notify:
1108
1109 ``only-notify``
1110 ---------------
1111
1112 -  IP Ranges, separated by commas or whitespace
1113 -  Default: 0.0.0.0/0, ::/0
1114
1115 For type=MASTER zones (or SLAVE zones with slave-renotify enabled)
1116 PowerDNS automatically sends NOTIFYs to the name servers specified in
1117 the NS records. By specifying networks/mask as whitelist, the targets
1118 can be limited. The default is to notify the world. To completely
1119 disable these NOTIFYs set ``only-notify`` to an empty value. Independent
1120 of this setting, the IP addresses or netmasks configured with
1121 :ref:`setting-also-notify` and ``ALSO-NOTIFY`` domain metadata
1122 always receive AXFR NOTIFYs.
1123
1124 IP addresses and netmasks can be excluded by prefixing them with a ``!``.
1125 To notify all IP addresses apart from the 192.168.0.0/24 subnet use the following::
1126
1127   only-notify=0.0.0.0/0, ::/0, !192.168.0.0/24
1128
1129 .. note::
1130   Even if NOTIFYs are limited by a netmask, PowerDNS first has to
1131   resolve all the hostnames to check their IP addresses against the
1132   specified whitelist. The resolving may take considerable time,
1133   especially if those hostnames are slow to resolve. If you do not need to
1134   NOTIFY the slaves defined in the NS records (e.g. you are using another
1135   method to distribute the zone data to the slaves), then set
1136   :ref:`setting-only-notify` to an empty value and specify the notification targets
1137   explicitly using :ref:`setting-also-notify` and/or
1138   :ref:`metadata-also-notify` domain metadata to avoid this potential bottleneck.
1139
1140 .. note::
1141   If your slaves support Internet Protocol version, which your master does not,
1142   then set ``only-notify`` to include only supported protocol version.
1143   Otherwise there will be error trying to resolve address.
1144
1145   For example, slaves support both IPv4 and IPv6, but PowerDNS master have only IPv4,
1146   so allow only IPv4 with ``only-notify``::
1147
1148     only-notify=0.0.0.0/0
1149
1150 .. _setting-out-of-zone-additional-processing:
1151
1152 ``out-of-zone-additional-processing``
1153 -------------------------------------
1154
1155 .. versionchanged:: 4.2.0
1156   This setting has been removed.
1157
1158 -  Boolean
1159 -  Default: yes
1160
1161 Do out of zone additional processing. This means that if a malicious
1162 user adds a '.com' zone to your server, it is not used for other domains
1163 and will not contaminate answers. Do not enable this setting if you run
1164 a public DNS service with untrusted users.
1165
1166 The docs had previously indicated that the default was "no", but the
1167 default has been "yes" since 2005.
1168
1169 .. _setting-outgoing-axfr-expand-alias:
1170
1171 ``outgoing-axfr-expand-alias``
1172 ------------------------------
1173
1174 -  Boolean
1175 -  Default: no
1176
1177 If this is enabled, ALIAS records are expanded (synthesised to their
1178 A/AAAA) during outgoing AXFR. This means slaves will not automatically
1179 follow changes in those A/AAAA records unless you AXFR regularly!
1180
1181 If this is disabled (the default), ALIAS records are sent verbatim
1182 during outgoing AXFR. Note that if your slaves do not support ALIAS,
1183 they will return NODATA for A/AAAA queries for such names.
1184
1185 .. _setting-prevent-self-notification:
1186
1187 ``prevent-self-notification``
1188 -----------------------------
1189
1190 -  Boolean
1191 -  Default: yes
1192
1193 PowerDNS Authoritative Server attempts to not send out notifications to
1194 itself in master mode. In very complicated situations we could guess
1195 wrong and not notify a server that should be notified. In that case, set
1196 prevent-self-notification to "no".
1197
1198 .. _setting-query-cache-ttl:
1199
1200 ``query-cache-ttl``
1201 -------------------
1202
1203 -  Integer
1204 -  Default: 20
1205
1206 Seconds to store queries with an answer in the Query Cache. See :ref:`query-cache`.
1207
1208 .. _setting-query-local-address:
1209
1210 ``query-local-address``
1211 -----------------------
1212
1213 -  IPv4 Address
1214 -  Default: 0.0.0.0
1215
1216 The IP address to use as a source address for sending queries. Useful if
1217 you have multiple IPs and PowerDNS is not bound to the IP address your
1218 operating system uses by default for outgoing packets.
1219
1220 .. _setting-query-local-address6:
1221
1222 ``query-local-address6``
1223 ------------------------
1224
1225 -  IPv6 Address
1226 -  Default: '::'
1227
1228 Source IP address for sending IPv6 queries.
1229
1230 .. _setting-query-logging:
1231
1232 ``query-logging``
1233 -----------------
1234
1235 -  Boolean
1236 -  Default: no
1237
1238 Boolean, hints to a backend that it should log a textual representation
1239 of queries it performs. Can be set at runtime.
1240
1241 .. _setting-queue-limit:
1242
1243 ``queue-limit``
1244 ---------------
1245
1246 -  Integer
1247 -  Default: 1500
1248
1249 Maximum number of milliseconds to queue a query. See :doc:`performance`.
1250
1251 .. _setting-receiver-threads:
1252
1253 ``receiver-threads``
1254 --------------------
1255
1256 -  Integer
1257 -  Default: 1
1258
1259 Number of receiver (listening) threads to start. See :doc:`performance`.
1260
1261 .. _setting-recursive-cache-ttl:
1262
1263 ``recursive-cache-ttl``
1264 -----------------------
1265
1266 -  Integer
1267 -  Default: 10
1268 -  Removed in: 4.1.0
1269
1270 Seconds to store recursive packets in the :ref:`packet-cache`.
1271
1272 .. _setting-recursor:
1273
1274 ``recursor``
1275 ------------
1276
1277 -  IP Address
1278
1279 .. deprecated:: 4.1.0
1280
1281 If set, recursive queries will be handed to the recursor specified here.
1282
1283 .. _setting-resolver:
1284
1285 ``resolver``
1286 ------------
1287
1288 -  IP Addresses with optional port, separated by commas
1289 -  Added in: 4.1.0
1290
1291 Use these resolver addresses for ALIAS and the internal stub resolver.
1292 If this is not set, ``/etc/resolv.conf`` is parsed for upstream
1293 resolvers.
1294
1295 .. _setting-retrieval-threads:
1296
1297 ``retrieval-threads``
1298 ---------------------
1299
1300 -  Integer
1301 -  Default: 2
1302
1303 Number of AXFR slave threads to start.
1304
1305 .. _setting-send-signed-notify:
1306
1307 ``send-signed-notify``
1308 ----------------------
1309
1310 -  Boolean
1311 -  Default: yes
1312
1313 If yes, outgoing NOTIFYs will be signed if a TSIG key is configured for the zone.
1314 If there are multiple TSIG keys configured for a domain, PowerDNS will use the
1315 first one retrieved from the backend, which may not be the correct one for the
1316 respective slave. Hence, in setups with multiple slaves with different TSIG keys
1317 it may be required to send NOTIFYs unsigned.
1318
1319 .. _setting-setgid:
1320
1321 ``setgid``
1322 ----------
1323
1324 -  String
1325
1326 If set, change group id to this gid for more security. See :doc:`security`.
1327
1328 .. _setting-setuid:
1329
1330 ``setuid``
1331 ----------
1332
1333 -  String
1334
1335 If set, change user id to this uid for more security. See :doc:`security`.
1336
1337 .. _setting-slave:
1338
1339 ``slave``
1340 ---------
1341
1342 -  Boolean
1343 -  Default: no
1344
1345 Turn on slave support. See :ref:`slave-operation`.
1346
1347 .. _setting-slave-cycle-interval:
1348
1349 ``slave-cycle-interval``
1350 ------------------------
1351
1352 -  Integer
1353 -  60
1354
1355 On a master, this is the amounts of seconds between the master checking
1356 the SOA serials in its database to determine to send out NOTIFYs to the
1357 slaves. On slaves, this is the number of seconds between the slave
1358 checking for updates to zones.
1359
1360 .. _setting-slave-renotify:
1361
1362 ``slave-renotify``
1363 ------------------
1364
1365 -  Boolean
1366 -  Default: no
1367
1368 This setting will make PowerDNS renotify the slaves after an AXFR is
1369 *received* from a master. This is useful when using when running a
1370 signing-slave.
1371
1372 .. _setting-signing-threads:
1373
1374 ``signing-threads``
1375 -------------------
1376
1377 -  Integer
1378 -  Default: 3
1379
1380 Tell PowerDNS how many threads to use for signing. It might help improve
1381 signing speed by changing this number.
1382
1383 .. _setting-soa-expire-default:
1384
1385 ``soa-expire-default``
1386 ----------------------
1387
1388 -  Integer
1389 -  Default: 604800
1390
1391 Default :ref:`types-soa` expire.
1392
1393 .. _setting-soa-minimum-ttl:
1394
1395 ``soa-minimum-ttl``
1396 -------------------
1397
1398 -  Integer
1399 -  Default: 3600
1400
1401 Default :ref:`types-soa` minimum ttl.
1402
1403 .. _setting-soa-refresh-default:
1404
1405 ``soa-refresh-default``
1406 -----------------------
1407
1408 -  Integer
1409 -  Default: 10800
1410
1411 Default :ref:`types-soa` refresh.
1412
1413 .. _setting-soa-retry-default:
1414
1415 ``soa-retry-default``
1416 ---------------------
1417
1418 -  Integer
1419 -  Default: 3600
1420
1421 Default :ref:`types-soa` retry.
1422
1423 .. _setting-socket-dir:
1424
1425 ``socket-dir``
1426 --------------
1427
1428 -  Path
1429
1430 Where the controlsocket will live. The default depends on
1431 ``LOCALSTATEDIR`` during compile-time (usually ``/var/run`` or
1432 ``/run``). See :ref:`control-socket`.
1433
1434 This path will also contain the pidfile for this instance of PowerDNS
1435 called ``pdns.pid`` by default. See :ref:`setting-config-name`
1436 and :doc:`Virtual Hosting <guides/virtual-instances>` how this can differ.
1437
1438 .. _setting-supermaster:
1439
1440 ``supermaster``
1441 ---------------
1442
1443 -  Boolean
1444 -  Default: no
1445
1446 .. versionadded:: 4.2.0
1447
1448 Turn on supermaster support. See :ref:`supermaster-operation`.
1449
1450 .. _setting-tcp-control-address:
1451
1452 ``tcp-control-address``
1453 -----------------------
1454
1455 -  IP Address
1456
1457 Address to bind to for TCP control.
1458
1459 .. _setting-tcp-control-port:
1460
1461 ``tcp-control-port``
1462 --------------------
1463
1464 -  Integer
1465 -  Default: 53000
1466
1467 Port to bind to for TCP control.
1468
1469 .. _setting-tcp-control-range:
1470
1471 ``tcp-control-range``
1472 ---------------------
1473
1474 -  IP Ranges, separated by commas or whitespace
1475
1476 Limit TCP control to a specific client range.
1477
1478 .. _setting-tcp-control-secret:
1479
1480 ``tcp-control-secret``
1481 ----------------------
1482
1483 -  String
1484
1485 Password for TCP control.
1486
1487 .. _setting-tcp-fast-open:
1488
1489 ``tcp-fast-open``
1490 -----------------
1491
1492 -  Integer
1493 -  Default: 0 (Disabled)
1494
1495 .. versionadded:: 4.1.0
1496
1497 Enable TCP Fast Open support, if available, on the listening sockets.
1498 The numerical value supplied is used as the queue size, 0 meaning
1499 disabled.
1500
1501 .. _setting-tcp-idle-timeout:
1502
1503 ``tcp-idle-timeout``
1504 --------------------
1505
1506 -  Integer
1507 -  Default: 5
1508
1509 Maximum time in seconds that a TCP DNS connection is allowed to stay
1510 open while being idle, meaning without PowerDNS receiving or sending
1511 even a single byte.
1512
1513 .. _setting-traceback-handler:
1514
1515 ``traceback-handler``
1516 ---------------------
1517
1518 -  Boolean
1519 -  Default: yes
1520
1521 Enable the Linux-only traceback handler.
1522
1523 .. _setting-trusted-notification-proxy:
1524
1525 ``trusted-notification-proxy``
1526 ------------------------------
1527
1528 -  String
1529
1530 IP address of incoming notification proxy
1531
1532 .. _setting-udp-truncation-threshold:
1533
1534 ``udp-truncation-threshold``
1535 ----------------------------
1536
1537 -  Integer
1538 -  Default: 1232
1539
1540 EDNS0 allows for large UDP response datagrams, which can potentially
1541 raise performance. Large responses however also have downsides in terms
1542 of reflection attacks. Maximum value is 65535, but values above
1543 4096 should probably not be attempted.
1544
1545 .. note:: Why 1232?
1546
1547   1232 is the largest number of payload bytes that can fit in the smallest IPv6 packet.
1548   IPv6 has a minimum MTU of 1280 bytes (:rfc:`RFC 8200, section 5 <8200#section-5>`), minus 40 bytes for the IPv6 header, minus 8 bytes for the UDP header gives 1232, the maximum payload size for the DNS response.
1549
1550 .. _setting-version-string:
1551
1552 ``version-string``
1553 ------------------
1554
1555 -  Any of: ``anonymous``, ``powerdns``, ``full``, String
1556 -  Default: full
1557
1558 When queried for its version over DNS
1559 (``dig chaos txt version.bind @pdns.ip.address``), PowerDNS normally
1560 responds truthfully. With this setting you can overrule what will be
1561 returned. Set the ``version-string`` to ``full`` to get the default
1562 behaviour, to ``powerdns`` to just make it state
1563 ``served by PowerDNS - http://www.powerdns.com``. The ``anonymous``
1564 setting will return a ServFail, much like Microsoft nameservers do. You
1565 can set this response to a custom value as well.
1566
1567 .. _setting-webserver:
1568
1569 ``webserver``
1570 -------------
1571
1572 -  Boolean
1573 -  Default: no
1574
1575 Start a webserver for monitoring. See :doc:`performance`".
1576
1577 .. versionchanged:: 4.1.0
1578   It was necessary to enable the webserver to use the REST API, this is no longer the case.
1579
1580 .. _setting-webserver-address:
1581
1582 ``webserver-address``
1583 ---------------------
1584
1585 -  IP Address
1586 -  Default: 127.0.0.1
1587
1588 IP Address for webserver/API to listen on.
1589
1590 .. _setting-webserver-allow-from:
1591
1592 ``webserver-allow-from``
1593 ------------------------
1594
1595 -  IP ranges, separated by commas or whitespace
1596 -  Default: 127.0.0.1,::1
1597
1598 .. versionchanged:: 4.1.0
1599
1600     Default is now 127.0.0.1,::1, was 0.0.0.0/0,::/0 before.
1601
1602 Webserver/API access is only allowed from these subnets.
1603
1604 .. _setting-webserver-password:
1605
1606 ``webserver-password``
1607 ----------------------
1608
1609 -  String
1610
1611 The plaintext password required for accessing the webserver.
1612
1613 .. _setting-webserver-port:
1614
1615 ``webserver-port``
1616 ------------------
1617
1618 -  Integer
1619 -  Default: 8001
1620
1621 The port where webserver/API will listen on.
1622
1623 .. _setting-webserver-print-arguments:
1624
1625 ``webserver-print-arguments``
1626 -----------------------------
1627
1628 -  Boolean
1629 -  Default: no
1630
1631 If the webserver should print arguments.
1632
1633 .. _setting-write-pid:
1634
1635 ``write-pid``
1636 -------------
1637
1638 -  Boolean
1639 -  Default: yes
1640
1641 If a PID file should be written.
1642
1643 .. _setting-xfr-max-received-mbytes:
1644
1645 ``xfr-max-received-mbytes``
1646 ---------------------------
1647
1648 -  Integer
1649 -  Default: 100
1650
1651 Specifies the maximum number of received megabytes allowed on an
1652 incoming AXFR/IXFR update, to prevent resource exhaustion. A value of 0
1653 means no restriction.