Reloading is currently done only when a request (or zone transfer) for a
zone comes in, and then only after :ref:`setting-bind-check-interval`
-seconds have passed after the last check. If a change occurred, access
+seconds have passed since the last check. If a change occurred, access
to the zone is disabled, the file is reloaded, access is restored, and
the question is answered. For regular zones, reloading is fast enough to
answer the question which lead to the reload within the DNS timeout.
If :ref:`setting-bind-check-interval` is specified as
-zero, no checks will be performed until the ``pdns_control reload`` is
-given.
+zero, no checks will be performed until the ``pdns_control reload`` command
+is issued.
Please note that also the :ref:`setting-slave-cycle-interval` setting
controls how often a master would notify a slave about changes.
``bind-reload-now <domain>``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Reloads a zone from disk NOW, reporting back results.
+Reloads a zone from disk immediately, reporting back results.
``rediscover``
~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. note::
- This section is only relevant for user who use SQL to change records and zones.
+ This section is only relevant for users who use SQL to change records and zones.
Two additional fields in the 'records' table are important: 'auth' and
'ordername'. These fields are set correctly on an incoming zone
:doc:`domain metadata <../domainmetadata>` for a domain.
- ``get-domain-metadata-query``: Get a single piece of
:doc:`domain metadata <../domainmetadata>`.
-- ``clear-domain-metadata-query``: Delete a single entry of domain
- metadata.
-- ``clear-domain-all-metadata-query``: Remove all domain metadata for a
- domain.
-- ``set-domain-metadata-query``: Add domain metadata for a zone.
+- ``clear-domain-metadata-query``: Delete a single entry of
+ :doc:`domain metadata <../domainmetadata>`.
+- ``clear-domain-all-metadata-query``: Remove all
+ :doc:`domain metadata <../domainmetadata>` for a domain.
+- ``set-domain-metadata-query``: Add
+ :doc:`domain metadata <../domainmetadata>` for a zone.
- ``add-domain-key-query``: Called to a cryptokey to a domain.
- ``list-domain-keys-query``: Called to get all cryptokeys for a
- ``list-comments-query``: Called to get all comments in a zone.
Returns fields: domain_id, name, type, modified_at, account,
comment.
-- ``insert-comment-query`` Called to create a single comment for a
+- ``insert-comment-query``: Called to create a single comment for a
specific RRSet. Given fields: domain_id, name, type, modified_at,
account, comment
- ``delete-comment-rrset-query``: Called to delete all comments for a
This backend (which is a.k.a. the YAML backend) allows visitors to be sent to a server closer to them, with
no appreciable delay, as would otherwise be incurred with a protocol
-level redirect. Additionally, the Geo Backend can be used to provide
+level redirect. Additionally, the GeoIP backend can be used to provide
service over several clusters, any of which can be taken out of use
easily, for example for maintenance purposes. This backend can utilize
EDNS Client Subnet extension for decision making, if provided in query
(default "") : Path to the object to authenticate against. Should only
be used, if the LDAP server doesn't support anonymous binds and with the
-"simple" bindmethod.
+"simple" :ref:`setting-ldap-bindmethod`.
.. _setting-ldap-secret:
^^^^^^^^^^^^^^^
(default "") : Password for authentication against the object specified
-by ldap-binddn. Only used when "bindmethod" is "simple".
+by ldap-binddn. Only used when :ref:`setting-ldap-bindmethod` is "simple".
.. _setting-ldap-krb5-keytab:
^^^^^^^^^^^^^^^^^^^^
(default: "") : Full path to the keytab file to use to authenticate.
-This is only used when "bindmethod" is set to "gssapi". The keytab must,
-ideally, contain only one principal (or to put it otherwise, only the
-first principal found in the keytab will be used).
+This is only used when :ref:`setting-ldap-bindmethod` is set to "gssapi".
+The keytab must, ideally, contain only one principal (or to put it otherwise,
+only the first principal found in the keytab will be used).
.. _setting-ldap-krb5-ccache:
``lmdb-shards``
^^^^^^^^^^^^^^^^^
-Records database will be split into this number of shards e.g. lmdb-shards=64
+Records database will be split into this number of shards e.g. lmdb-shards=64.
Default is 2 on 32 bits systems, and 64 on 64 bits systems.
.. _setting-lmdb-sync-mode:
``mapasync`` choice removed
-* Synchronisation mode: sync, nosync, nometasync
-* Default: sync
+Synchronisation mode: one of sync, nosync, nometasync (default: sync).
``sync`` (default since 4.9.0)
- LMDB synchronous mode. Safest option, but also slightly slower. Can also be enabled with ``lmdb-sync-mode=``
+ LMDB synchronous mode. Safest option, but also slightly slower. Can also be enabled with ``lmdb-sync-mode=``
``nosync``
don't flush systems buffers to disk when committing a transaction.
``lmdb-schema-version``
^^^^^^^^^^^^^^^^^^^^^^^
-Determines the maximum schema version LMDB is allowed to upgrade to. If the on disk LMDB database has a lower version than the current version of the LMDB schema the backend will not start, unless this setting allows it to upgrade the schema. If the version of the DB is already the same as the current schema version this setting is not checked and the backend starts normally.
+Determines the maximum schema version LMDB is allowed to upgrade to. If the on disk LMDB database has a lower version than the current version of the LMDB schema the backend will not start, unless this setting allows it to upgrade the schema. If the version of the DB is already the same as the current schema version this setting is not checked and the backend will start normally.
-The default value for this setting is the highest supported schema version for the version of PowerDNS you are starting. if you want to prevent automatic schema upgrades, explicitly set this setting to the current default before upgrading PowerDNS.
+The default value for this setting is the highest supported schema version for the version of PowerDNS you are starting. If you want to prevent automatic schema upgrades, explicitly set this setting to the current default before upgrading PowerDNS.
================ ===================
PowerDNS Version LMDB Schema version
-----------------
There is a breaking change on v4.0 and later. Before version 4.0, the
-DNS names passed in queries were without trailing dot, after version 4.0
-the DNS names are sent with trailing dot. F.ex. example.org is now sent
+DNS names passed in queries were sent without a trailing dot, after version 4.0
+the DNS names are always sent with trailing dot. F.ex. example.org is now sent
as example.org.
In some (broken) network setups, the IP addresses provided in the
``list``
~~~~~~~~
-Lists all records for the zonename. If you are running dnssec, you
+Lists all records for the zonename. If you are running DNSSEC, you
should take care of setting auth to appropriate value, otherwise things
can go wrong.
~~~~~~~~~~~~~~~~~~~~~~~~
Returns the value(s) for variable kind for zone name. You **must**
-always return something, if there are no values, you shall return empty
+always return something, if there are no values, you shall return an empty
set.
* Mandatory: yes
Returns the value(s) for variable kind for zone name. Most commonly it's
one of NSEC3PARAM, PRESIGNED, SOA-EDIT. Can be others, too. You **must**
-always return something, if there are no values, you shall return empty
+always return something, if there are no values, you shall return an empty
array.
- Mandatory: No
Per zone settings
-----------------
-It is highly recommended to protect catalog zones with :doc:`TSIG <../tsig>`
+It is highly recommended to protect catalog zones with :doc:`TSIG <../tsig>`.
CATALOG-HASH
~~~~~~~~~~~~
Details
^^^^^^^
PowerDNS software sadly sometimes has critical security bugs.
-Even though we send out notifications of these via all channels available, we find that not everybody actually find out about our security releases.
+Even though we send out notifications of these via all channels available, we find that not everybody actually finds out about our security releases.
To solve this, PowerDNS software will start polling for security notifications, and log these periodically.
Secondly, the security status of the software will be reported using the built-in metrics.
dhcpdupdate. IN KEY 0 3 157 FYhvwsW1ZtFZqWzsMpqhbg==
The important bits are the name of the key (**dhcpdupdate**) and the
-hash of the key (**FYhvwsW1ZtFZqWzsMpqhbg==**
+hash of the key (**FYhvwsW1ZtFZqWzsMpqhbg==**)
-Using the details from the key you've just generated. Add the following
+Using the details from the freshly generated key, add the following
to your dhcpd.conf:
::
Setting up PowerDNS
~~~~~~~~~~~~~~~~~~~
-A number of small changes are needed to powerdns to make it accept
+A number of small changes are needed to PowerDNS to make it accept
dynamic updates from **dhcpd**.
-Enabled DNS update (:rfc:`2136`) support functionality in PowerDNS by adding
+Enable DNS update (:rfc:`2136`) support functionality in PowerDNS by adding
the following to the PowerDNS configuration file (pdns.conf).
.. code-block:: ini
This tells PowerDNS to:
-1. Enable DNS update support(:ref:`setting-dnsupdate`)
+1. Enable DNS update support (:ref:`setting-dnsupdate`)
2. Allow updates from NO ip-address (":ref:`setting-allow-dnsupdate-from`\ =")
-We just told powerdns (via the configuration file) that we accept
+We just told PowerDNS (via the configuration file) that we accept
updates from nobody via the :ref:`setting-allow-dnsupdate-from`
parameter. That's not very useful, so we're going to give permissions
per zone (including the appropriate reverse zone), via the
Per-zone AXFR ACLs can be stored in the domainmetadata table.
Each ACL specifies one subnet (v4 or v6), or the magical value 'AUTO-NS'
-that tries to allow all potential slaves in.
+that tries to allow all potential secondaries in.
Example:
--------------
.. versionadded:: 4.3.0
-If set to 1, will make PowerDNS renotify the slaves after an AXFR is received from a master.
+If set to 1, will make PowerDNS renotify the secondaries after an AXFR is received from a master.
Any other value means that no renotifies are done. If not set at all, action will depend on
the :ref:`setting-slave-renotify` setting.
--------
When serving this zone, modify the SOA serial number in one of several
-ways. Mostly useful to get slaves to re-transfer a zone regularly to get
+ways. Mostly useful to get secondaries to re-transfer a zone regularly to get
fresh RRSIGs. See the :ref:`DNSSEC
documentation <soa-edit-ensure-signature-freshness-on-slaves>`
for more information.
--------------------
This setting allows you to set the TSIG key required to do an :doc:`dnsupdate`.
-If :ref:`GSS-TSIG <tsig-gss-tsig>` is enabled, you can put kerberos principals here as well.
+If :ref:`GSS-TSIG <tsig-gss-tsig>` is enabled, you can put Kerberos principals here as well.
Extra metadata
--------------
25 mail.example.com
If this is not the output you get, remove ``+short`` to see the full output so you can find out what went wrong.
-The first problem could be that PowerDNS has a :ref:`packet-cache` and a :ref:`query-cache` performance reasons.
+The first problem could be that PowerDNS has a :ref:`packet-cache` and a :ref:`query-cache` for performance reasons.
If you see old, or no, data right after changing records, wait for :ref:`setting-cache-ttl`,
-:ref:`setting-negquery-cache-ttl`, :ref:`setting-query-cache-ttl`, or :ref:`zone-cache-refresh-interval`
+:ref:`setting-negquery-cache-ttl`, :ref:`setting-query-cache-ttl`, or :ref:`setting-zone-cache-refresh-interval`
to expire before testing.
Now, run ``pdnsutil edit-zone example.com`` and try to add a few more records, and query them with dig to make sure they work.
:param values: table of weight, string (such as IPv4 or IPv6 address).
This function works almost like :func:`pickwhashed` while bringing the following properties:
+
- reordering the list of entries won't affect the distribution
- updating the weight of an entry will only affect a part of the distribution
- because of the previous properties, the CPU and memory cost is a bit higher than :func:`pickwhashed`
Hashes will be pre computed the first time such a record is hit and refreshed if needed. If updating the list is done often,
- the cash may grow. A cleanup routine is performed every :ref:`setting-lua-consistent-hashes-cleanup-interval` seconds (default 1h)
+ the cache may grow. A cleanup routine is performed every :ref:`setting-lua-consistent-hashes-cleanup-interval` seconds (default 1h)
and cleans cached entries for records that haven't been used for :ref:`setting-lua-consistent-hashes-expire-delay` seconds (default 24h)
An example::
Used for generating default hostnames from IPv6 wildcard reverse DNS records, e.g. ``*.1.0.0.2.ip6.arpa``
**For simplicity purposes, only small sections of IPv6 rDNS domains are used in most parts of this guide,**
- **as a full ip6.arpa record is around 80 characters long**
+ **as a full ip6.arpa record is around 80 characters long.**
See :func:`createReverse` for IPv4 records (in-addr.arpa)
$ dig +short AAAA 2001-a-b--1.static6.example.com @ns1.example.com
2001:a:b::1
- Since 4.8.0: a non-split full length format (``20010002000300040005000600070db8.example.com``) is also supported, optionally prefixed, in which case the last 32 characters will be considered.
+ Since 4.8.0: a non-split full length format (``20010002000300040005000600070db8.example.com``) is also supported, optionally prefixed, in which case only the last 32 characters will be considered.
.. function:: filterForward(address, masks[, fallback])
The default mode of operation for LUA records is to create a fresh Lua state for every query that hits a LUA record.
This way, different LUA records cannot accidentally interfere with each other, by leaving around global objects, or perhaps even deleting relevant functions.
However, creating a Lua state (and registering all our functions for it, see Reference below) takes measurable time.
-For users that are confident they can write Lua scripts that will not interfere with eachother, a mode is supported where Lua states are created on the first query, and then reused forever.
+For users that are confident they can write Lua scripts that will not interfere with each other, a mode is supported where Lua states are created on the first query, and then reused forever.
Note that the state is per-thread (for UDP, plus one shared state for all TCP), so while data sharing between LUA invocations is possible (useful for caching and reducing the cost of ``require``), there is no single shared Lua environment.
In non-scientific testing this has yielded up to 10x QPS increases.
It has these methods:
.. method:: ComboAddressSet:add(addr)
+ .. method:: ComboAddressSet:add(addrs)
+ .. method:: ComboAddressSet:add(ca)
- Add the given `addr` to set. `addr` can be of the following types
+ Add the given addresses to set. the parameter can be of the following types:
- :param ComboAddress addr: The `ComboAddress` object to add to set
:param string addr: Handy way to add `ComboAddress` from its string representation
- :param [string] addr: Add the given list of addresses to the set
+ :param [string] addrs: Add the given list of addresses to the set
+ :param ComboAddress ca: The `ComboAddress` object to add to set
.. code-block:: lua
.. method:: DNSHeader:getAD() -> bool
- Authenticated data from named
+ Authenticated data from name server
.. method:: DNSHeader:getAA() -> bool
.. function:: newDRR(name, type, ttl, content[, domainId[, auth]]) -> DNSResourceRecord
Returns a new :class:`DNSResourceRecord` object.
- .. todo describe the auth param
:param DNSName name: The name to the new record
:param string type: The name to create a DNSName for
:param int ttl: The TTL of the record
:param string content: The content of the record
:param int domainId: The optional domain ID of the zone the record belongs to
- :param int auth: ?
+ :param int auth: Whether the record is authoritative
.. todo complete LUA example below
.. code-block:: lua
- `pdns.loglevels.Critical`
- `pdns.loglevels.Debug`
- `pdns.loglevels.Emergency`
+ - `pdns.loglevels.Error`
- `pdns.loglevels.Info`
- `pdns.loglevels.Notice`
- `pdns.loglevels.Warning`
- - `pdns.loglevels.Error`
.. function:: pdnsrandom([upper_bound])
Adds ``masks`` to the NetMaskGroup.
- :param {str} mask: The masks to add.
+ :param {str} masks: The masks to add.
.. method:: NetMaskGroup:match(address) -> bool
~~~~~~~~~~~~~~~~~~~~~~~~
.. note::
- This assumes the schema provided with PowerDNS is in place
+ This assumes the schema provided with PowerDNS is in place.
In order to migrate to a Generic SQL backend, add all your domains to
the 'domains' table with the IP of your current master. On your current
script is invoked for each resource record read during the transfer, and
the outcome of the function defines what PowerDNS does with the records.
-What you can accomplish using a Lua script: - Ensure consistent values
-on SOA - Change incoming SOA serial number to a YYYYMMDDnn format -
-Ensure consistent NS RRset - Timestamp the zone transfer with a TXT
-record
+What you can accomplish using a Lua script:
+
+- Ensure consistent values on SOA
+- Change incoming SOA serial number to a YYYYMMDDnn format
+- Ensure consistent NS RRset
+- Timestamp the zone transfer with a TXT record
This script can be enabled like this::
result code of 0 together with a Lua table containing one or more
replacement records to be stored in the back-end database (if the table
is empty, no record is added). If you want your record(s) to be appended
-after the matching record, return 1 and table of record(s). If, on the
+after the matching record, return 1 and a table of record(s). If, on the
other hand, your function decides not to modify a record, it must return
-1 and an empty table indicating that PowerDNS should handle the
incoming record as normal.
function axfrfilter(remoteip, zone, record)
- -- Replace each HINFO records with this TXT
+ -- Replace each HINFO record with this TXT
if record:qtype() == pdns.HINFO then
resp = {}
resp[1] = {
The default values should work fine for many sites. When tuning, keep in
mind that the Query Cache mostly saves database access but that the
-Packet Cache also saves a lot of CPU because 0 internal processing is
+Packet Cache also saves a lot of CPU because zero internal processing is
done when answering a question from the Packet Cache.
Caches & Memory Allocations & glibc
^^^^^^^^^^^^^^^
Security status based on :ref:`securitypolling`.
+.. _stat-send-latency:
+
+send-latency
+^^^^^^^^^^^^
+Average number of microseconds needed to send the answer
+
.. _stat-servfail-packets:
servfail-packets
^^^^^^^^^^^^^^^^
Amount of packets that were dropped because they had to wait too long internally
-.. _stat-send-latency:
-
-send-latency
-^^^^^^^^^^^^
-Average number of microseconds needed to send the answer
-
.. _stat-udp-answers-bytes:
udp-answers-bytes
The content is a Base64-encoded secret.
.. note::
- Most backends require DNSSEC support enabled to support TSIG.
- For the Generic SQL Backend make sure to use the DNSSEC enabled schema
+ Most backends require DNSSEC support to be enabled to support TSIG.
+ For the Generic SQL Backend, make sure to use the DNSSEC-enabled schema
and to turn on the relevant '-dnssec' flag (for example,
``gmysql-dnssec``)!
If a user keytab is used, specify it using the ``KRB5_KTNAME`` environment variable when starting up PDNS server, which must be able to read the keytab file.
-In particular, if something does not work, read logs and ensure that your kerberos environment is ok before filing an issue.
+In particular, if something does not work, read logs and ensure that your Kerberos environment is functional before filing an issue.
Most common problems are time synchronization or changes done to the principal.
Setting up
projects / thirdparty / pdns.git / commitdiff
