diff --git a/.github/actions/spell-check/expect.txt b/.github/actions/spell-check/expect.txt index 63645a30359c..51742aa7028d 100644 --- a/.github/actions/spell-check/expect.txt +++ b/.github/actions/spell-check/expect.txt @@ -27,6 +27,7 @@ algoroll aliasmode allocs Altpeter +andersbrownworth Anderton anewid anid @@ -263,7 +264,6 @@ Darron dataformat datatracker Daugaard -davidmillerskt Davids davidtmiller Dayneko @@ -278,7 +278,6 @@ ddns ddos deactivatedomainkey debian -deboynepollard Deduktiva defcontent defpol @@ -383,7 +382,6 @@ dynbpf dyndns dynhandler dynmodules -eachother easydns ebpf ebpfblocklist @@ -626,6 +624,7 @@ janeczku Jatko Jaury Jauvin +jdebp Jeftovic Jelte Jermar @@ -781,7 +780,6 @@ mbed mbedtls MBOXFW mbytes -mdo Meerwald Mekking melpa @@ -926,7 +924,6 @@ nsspeeds NSTTL nsupdate nta -ntlworld Nuitari NULs NUMA @@ -975,7 +972,6 @@ ourserial outpacket outputbuffer outqueries -oxpedia PACKAGEVERSION packetcache packethandler @@ -1290,7 +1286,6 @@ Soroceanu sortlist sourcecode SOURCEDIR -sourceforge sourcelink sourceware Spaans diff --git a/docs/appendices/backend-writers-guide.rst b/docs/appendices/backend-writers-guide.rst index f668bb7c0ec0..f55272cf0022 100644 --- a/docs/appendices/backend-writers-guide.rst +++ b/docs/appendices/backend-writers-guide.rst @@ -67,10 +67,10 @@ following methods are relevant: { public: - virtual void lookup(const QType &qtype, const string &qdomain, DNSPacket *pkt_p=0, int zoneId=-1)=0; + virtual void lookup(const QType &qtype, const string &qdomain, int zoneId=-1, DNSPacket *pkt_p=nullptr)=0; virtual bool list(const string &target, int domain_id)=0; virtual bool get(DNSResourceRecord &r)=0; - virtual bool getSOA(const string &name, SOAData &soadata, DNSPacket *p=0); + virtual bool getSOA(const string &name, SOAData &soadata); }; Note that the first three methods must be implemented. ``getSOA()`` has @@ -84,9 +84,9 @@ that your backend will never be called reentrantly. Queries for wildcard names should be answered literally, without expansion. So, if a backend gets a question for "\*.powerdns.com", it should only answer with data if there is an actual - "\*.powerdns.com" name + "\*.powerdns.com" name. -Some examples, a more formal specification is down below. A normal +Some examples, a more formal specification can be found down below. A normal lookup starts like this: .. code-block:: cpp @@ -167,7 +167,7 @@ furthermore, only about its A record: return false; // we don't support AXFR } - void lookup(const QType &type, const string &qdomain, DNSPacket *p, int zoneId) + void lookup(const QType &type, const string &qdomain, int zoneId, DNSPacket *p) { if(type.getCode()!=QType::A || qdomain!="random.powerdns.com") // we only know about random.powerdns.com A d_answer=""; // no answer @@ -274,7 +274,7 @@ Classes .. cpp:class:: DNSResourceRecord -.. cpp:member:: std::string DNSResourceRecord::qname +.. cpp:member:: DNSName DNSResourceRecord::qname Name of this record @@ -296,7 +296,7 @@ Classes .. cpp:member:: time_t DNSResourceRecord::last_modified - If unzero, last time_t this record was changed + If non-zero, last time_t this record was changed .. cpp:member:: bool DNSResourceRecord::auth @@ -310,14 +310,10 @@ Classes .. cpp:class:: SOAData -.. cpp:member:: string SOAData::nameserver +.. cpp:member:: DNSName SOAData::nameserver Name of the primary nameserver of this zone -.. cpp:member:: string SOAData::hostmaster - - Hostmaster of this domain. May contain an @ - .. cpp:member:: uint32_t SOAData::serial Serial number of this zone @@ -334,9 +330,9 @@ Classes If zone pulls failed for this long, retire records -.. cpp:member:: uint32_t SOAData::default_ttl +.. cpp:member:: uint32_t SOAData::minimum - Difficult + Minimum acceptable value for TTL .. cpp:member:: int SOAData::domain_id @@ -349,7 +345,7 @@ Classes Methods ~~~~~~~ -.. cpp:function:: void DNSBackend::lookup(const QType &qtype, const string &qdomain, DNSPacket *pkt=nullptr, int zoneId=-1) +.. cpp:function:: void DNSBackend::lookup(const QType &qtype, const string &qdomain, int zoneId=-1, DNSPacket *pkt=nullptr) This function is used to initiate a straight lookup for a record of name 'qdomain' and type 'qtype'. A QType can be converted into an integer by @@ -419,9 +415,9 @@ Methods .. cpp:function:: bool DNSBackend::getSOA(const string &name, SOAData &soadata) If the backend considers itself authoritative over domain ``name``, this - method should fill out the passed **SOAData** structure and return a - positive number. If the backend is functioning correctly, but does not - consider itself authoritative, it should return 0. In case of errors, an + method should fill out the passed **SOAData** structure and return true. + If the backend is functioning correctly, but does not consider itself + authoritative, it should return false. In case of errors, an PDNSException should be thrown. Reporting errors @@ -453,13 +449,13 @@ will call this method after launching the backend. In the ``declareArguments()`` method, the function ``declare()`` is available. The exact definitions: -.. cpp:function:: void DNSBackend::declareArguments(const string &suffix="") +.. cpp:function:: void BackendFactory::declareArguments(const string &suffix="") This method is called to allow a backend to register configurable parameters. The suffix is the sub-name of this module. There is no need - to touch this suffix, just pass it on to the declare method. + to touch this suffix, just pass it on to the ``declare`` method. -.. cpp:function:: void DNSBackend::declare(const string &suffix, const string ¶m, const string &explanation, const string &value) +.. cpp:function:: void BackendFactory::declare(const string &suffix, const string ¶m, const string &explanation, const string &value) The suffix is passed to your method, and can be passed on to declare. **param** is the name of your parameter. **explanation** is what will @@ -498,7 +494,7 @@ available. The exact definitions: .. cpp:function:: int DNSBackend::getArgAsNum(const string &key) - Returns the numerical value of a parameter. Uses ``atoi()`` internally + Returns the numerical value of a parameter. Uses ``strtol()`` internally. Sample usage from the BIND backend: getting the 'check-interval' setting: @@ -537,9 +533,9 @@ If this is the case, PowerDNS dubs the domain 'stale', and schedules a transfer of data from the remote. This transfer remains scheduled until the serial numbers remote and locally are identical again. -This theory is implemented by the ``getUnfreshSlaveInfos`` method, which +This theory is implemented by the ``getUnfreshSecondaryInfos`` method, which is called on all backends periodically. This method fills a vector of -**SlaveDomain**\ s with domains that are unfresh and possibly stale. +**DomainInfo**\ s with domains that are unfresh and possibly stale. PowerDNS then retrieves the SOA of those domains remotely and locally and creates a list of stale domains. For each of these domains, PowerDNS @@ -555,28 +551,28 @@ The following excerpt from the DNSBackend shows the relevant functions: class DNSBackend { public: /* ... */ - virtual bool getDomainInfo(const string &domain, DomainInfo &di); - virtual bool isMaster(const string &name, const string &ip); - virtual bool startTransaction(const string &qname, int id); - virtual bool commitTransaction(); - virtual bool abortTransaction(); - virtual bool feedRecord(const DNSResourceRecord &rr, string *ordername=0); - virtual void getUnfreshSlaveInfos(vector* domains); - virtual void setFresh(uint32_t id); + virtual bool getDomainInfo(const string &domain, DomainInfo &di, bool getSerial = true); + virtual bool isPrimary(const ComboAddress& ipAddress); + virtual bool startTransaction(const string &qname, int id); + virtual bool commitTransaction(); + virtual bool abortTransaction(); + virtual bool feedRecord(const DNSResourceRecord &rr, const DNSName &ordername, bool ordernameIsNSEC3 = false); + virtual void getUnfreshSecondaryInfos(vector* domains); + virtual void setFresh(uint32_t id); /* ... */ } The mentioned DomainInfo struct looks like this: -.. cpp:class:: DomainInfo +.. cpp:struct:: DomainInfo .. cpp:member:: uint32_t DomainInfo::id ID of this zone within this backend -.. cpp:member:: string DomainInfo::master +.. cpp:member:: vector DomainInfo::primaries - IP address of the primary of this domain, if any + IP addresses of the primary of this domain (may be empty) .. cpp:member:: uint32_t DomainInfo::serial @@ -600,7 +596,7 @@ The mentioned DomainInfo struct looks like this: .. cpp:enum:: DomainKind - The kind of domain, one of {Master,Slave,Native}. + The kind of domain, one of {Primary,Secondary,Native}. These functions all have a default implementation that returns false - which explains that these methods can be omitted in simple backends. @@ -609,21 +605,21 @@ make sure that the 'DNSBackend \*db' field of the SOAData record is filled out correctly - it is used to determine which backend will house this zone. -.. cpp:function:: bool DomainInfo::isMaster(const string &name, const string &ip) +.. cpp:function:: bool DomainInfo::isPrimary(const ComboAddress& ipAddress) - If a backend considers itself a secondary for the domain **name** and if the - IP address in **ip** is indeed a primary, it should return true. False + If a backend considers itself a secondary for the given domain and if the + IP address in **ipAddress** is indeed a primary, it should return true. False otherwise. This is a first line of checks to guard against reloading a domain unnecessarily. -.. cpp:function:: void DomainInfo::getUnfreshSlaveInfos(vector\* domains) +.. cpp:function:: void DomainInfo::getUnfreshSecondaryInfos(vector\* domains) When called, the backend should examine its list of secondary domains and add any unfresh ones to the domains vector. -.. cpp:function:: bool DomainInfo::getDomainInfo(const string &name, DomainInfo & di) +.. cpp:function:: bool DomainInfo::getDomainInfo(const string &name, DomainInfo & di, boot getSerial) - This is like ``getUnfreshSlaveInfos``, but for a specific domain. If the + This is like ``getUnfreshSecondaryInfos``, but for a specific domain. If the backend considers itself authoritative for the named zone, ``di`` should be filled out, and 'true' be returned. Otherwise return false. @@ -633,7 +629,7 @@ this zone. committed or rolled back atomically later on. In SQL terms, this function should **BEGIN** a transaction and **DELETE** all records. -.. cpp:function:: bool DomainInfo::feedRecord(const DNSResourceRecord &rr, string *ordername) +.. cpp:function:: bool DomainInfo::feedRecord(const DNSResourceRecord &rr, const DNSName &ordername, bool ordernameIsNSEC3) Insert this record. @@ -649,7 +645,7 @@ this zone. Indicate that a domain has either been updated or refreshed without the need for a retransfer. This causes the domain to vanish from the vector - modified by ``getUnfreshSlaveInfos()``. + modified by ``getUnfreshSecondaryInfos()``. PowerDNS will always call ``startTransaction()`` before making calls to ``feedRecord()``. Although it is likely that ``abortTransaction()`` will @@ -686,7 +682,7 @@ implement the following method: class DNSBackend { - virtual bool superMasterBackend(const string &ip, const string &domain, const vector&nsset, string *account, DNSBackend **db) + virtual bool autoPrimaryBackend(const string &ip, const DNSName &domain, const vector&nsset, string *nameserver, string *account, DNSBackend **db) }; This function gets called with the IP address of the potential @@ -711,8 +707,8 @@ whenever a domain is changed. Periodically, PowerDNS queries backends for domains that may have changed, and sends out notifications to secondary nameservers. -In order to do so, PowerDNS calls the ``getUpdatedMasters()`` method. -Like the ``getUnfreshSlaveInfos()`` function mentioned above, this +In order to do so, PowerDNS calls the ``getUpdatedPrimaries()`` method. +Like the ``getUnfreshSecondaryInfos()`` function mentioned above, this should add changed domain names to the vector passed. The following excerpt from the DNSBackend shows the relevant functions: @@ -722,27 +718,27 @@ The following excerpt from the DNSBackend shows the relevant functions: class DNSBackend { public: /* ... */ - virtual void getUpdatedMasters(vector* domains); + virtual void getUpdatedPrimaries(vector* domains, std::unordered_set &catalogs, CatalogHashMap &catalogHashes); virtual void setNotified(uint32_t id, uint32_t serial); /* ... */ } -These functions all have a default implementation that returns false - +These functions all have a default implementation that doesn't do anything - which explains that these methods can be omitted in simple backends. Furthermore, unlike with simple backends, a secondary capable backend must make sure that the 'DNSBackend \*db' field of the SOAData record is filled out correctly - it is used to determine which backend will house this zone. -.. cpp:function:: void DNSBackend::getUpdatedMasters(vector* domains) +.. cpp:function:: void DNSBackend::getUpdatedPrimaries(vector* domains, std::unordered_set &catalogs, CatalogHashMap &catalogHashes) - When called, the backend should examine its list of master domains and + When called, the backend should examine its list of primary domains and add any changed ones to the :cpp:class:`DomainInfo` vector. -.. cpp:function:: bool DNSBackend::setNotified(uint32_t domain_id, uint32_t serial) +.. cpp:function:: void DNSBackend::setNotified(uint32_t domain_id, uint32_t serial) Indicate that notifications have been queued for this domain and that it - need not be considered 'updated' anymore + need not be considered 'updated' anymore. DNS update support ------------------ @@ -757,16 +753,16 @@ other update/remove functionality at a later stage. class DNSBackend { public: /* ... */ - virtual bool startTransaction(const string &qname, int id); + virtual bool startTransaction(const DNSName &qname, int id); virtual bool commitTransaction(); virtual bool abortTransaction(); - virtual bool feedRecord(const DNSResourceRecord &rr, string *ordername); - virtual bool replaceRRSet(uint32_t domain_id, const string& qname, const QType& qt, const vector& rrset) - virtual bool listSubZone(const string &zone, int domain_id); + virtual bool feedRecord(const DNSResourceRecord &rr, DNSName &ordername, bool ordernameIsNSEC3); + virtual bool replaceRRSet(uint32_t domain_id, const DNSName& qname, const QType& qt, const vector& rrset) + virtual bool listSubZone(const DNSName &zone, int domain_id); /* ... */ } -.. cpp:function:: virtual bool DNSBackend::startTransaction(const string &qname, int id) +.. cpp:function:: virtual bool DNSBackend::startTransaction(const DNSName &qname, int id) See :cpp:func:`above `. Please note that this function now receives a negative number (-1), which @@ -781,17 +777,17 @@ other update/remove functionality at a later stage. See cpp:func:`above `. Method is called when an exception is received. -.. cpp:function:: virtual bool DNSBackend::feedRecord(const DNSResourceRecord &rr, string *ordername) +.. cpp:function:: virtual bool DNSBackend::feedRecord(const DNSResourceRecord &rr, const DNSName &ordername, bool ordernameIsNSEC3) See :cpp:func:`above `. Please keep in mind that the zone is not empty because - ``startTransaction()`` was called different. + ``startTransaction()`` was called differently. -.. cpp:function:: virtual bool DNSBackend::listSubZone(const string &name, int domain_id) +.. cpp:function:: virtual bool DNSBackend::listSubZone(const DNSName &name, int domain_id) This method is needed for rectification of a zone after NS-records have been added. For DNSSEC, we need to know which records are below the - currently added record. ``listSubZone()`` is used like ``list()`` which + currently added record. ``listSubZone()`` is used like ``list()``, which means PowerDNS will call ``get()`` after this method. The default SQL query looks something like this:: @@ -799,10 +795,10 @@ other update/remove functionality at a later stage. select content,ttl,prio,type,domain_id,name from records where (name='%s' OR name like '%s') and domain_id=%d The method is not only used when adding records, but also to correct - ENT-records in powerdns. Make sure it returns every record in the tree + ENT-records in PowerDNS. Make sure it returns every record in the tree below the given record. -.. cpp:function:: virtual bool DNSBackend::replaceRRSet(uint32_t domain_id, const string& qname, const QType& qt, const vector& rrset) +.. cpp:function:: virtual bool DNSBackend::replaceRRSet(uint32_t domain_id, const DNSName& qname, const QType& qt, const vector& rrset) This method should remove all the records with ``qname`` of type ``qt``. ``qt`` might also be ANY, which means all the records with that @@ -852,7 +848,7 @@ In order for a backend to support the storage of TSIG keys, the following operat class DNSBackend { public: /* ... */ - virtual bool getTSIGKey(const DNSName& name, DNSName* algorithm, string* content); + virtual bool getTSIGKey(const DNSName& name, DNSName& algorithm, string& content); virtual bool setTSIGKey(const DNSName& name, const DNSName& algorithm, const string& content); virtual bool deleteTSIGKey(const DNSName& name); virtual bool getTSIGKeys(std::vector< struct TSIGKey > &keys); @@ -1018,13 +1014,13 @@ It has name, type, class, TTL, content length, and a content object of type ``DN class DNSRecordContent { public: - static std::shared_ptr mastermake(...); + static std::shared_ptr make(...); virtual std::string getZoneRepresentation(bool noDot=false) const = 0; - virtual void toPacket(DNSPacketWriter& pw)=0; - virtual string serialize(const DNSName& qname, bool canonic=false, bool lowerCase=false); + virtual void toPacket(DNSPacketWriter& pw) const =0; + string serialize(const DNSName& qname, bool canonic=false, bool lowerCase=false); virtual bool operator==(const DNSRecordContent& rhs); // compares presentation format - static shared_ptr deserialize(const DNSName& qname, uint16_t qtype, const string& serialized); + static shared_ptr deserialize(const DNSName& qname, uint16_t qtype, const string& serialized, uint16_t qclass=QClass::IN); void doRecordCheck(const struct DNSRecord&){} @@ -1053,7 +1049,7 @@ It is subclassed for all supported types: class DNSResourceRecord { public: - DNSResourceRecord() : last_modified(0), ttl(0), signttl(0), domain_id(-1), qclass(1), scopeMask(0), auth(1), disabled(0) {}; + DNSResourceRecord() : last_modified(0), ttl(0), signttl(0), domain_id(-1), qclass(1), scopeMask(0), auth(true), disabled(false) {}; static DNSResourceRecord fromWire(const DNSRecord& d); void setContent(const string& content); @@ -1079,4 +1075,4 @@ It is subclassed for all supported types: bool operator<(const DNSResourceRecord &b); -``DNSResourceRecord`` holds a DNS record with content in presentation format, as a string. \ No newline at end of file +``DNSResourceRecord`` holds a DNS record with content in presentation format, as a string. diff --git a/docs/appendices/compiling.rst b/docs/appendices/compiling.rst index 9873d1878e9c..02fb5de1a7f3 100644 --- a/docs/appendices/compiling.rst +++ b/docs/appendices/compiling.rst @@ -36,8 +36,8 @@ These releases are PGP-signed with one of these key-ids: Dependencies ------------ -To build the PowerDNS Authoritative Server, a C++ compiler with support for C++ 2011 is required. -This means gcc 4.9 and newer and clang 3.5 and newer. +To build the PowerDNS Authoritative Server, a C++ compiler with support for C++ 2017 is required. +This means gcc 7.1 and newer and clang 5 and newer. Furthermore, the Makefiles require GNU make, not BSD make. By default, the PowerDNS Authoritative Server requires the following libraries and headers: diff --git a/docs/backends/bind.rst b/docs/backends/bind.rst index 20273920062e..e4ab8a577945 100644 --- a/docs/backends/bind.rst +++ b/docs/backends/bind.rst @@ -166,16 +166,16 @@ not yet available, to prevent incomplete answers. 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 +Please note that also the :ref:`setting-xfr-cycle-interval` setting controls how often a master would notify a slave about changes. Especially in 'hidden master' configurations, where servers usually don't receive regular queries, you may want to lower that setting to a @@ -219,7 +219,7 @@ Lists all zones that have problems, and what those problems are. ``bind-reload-now `` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Reloads a zone from disk NOW, reporting back results. +Reloads a zone from disk immediately, reporting back results. ``rediscover`` ~~~~~~~~~~~~~~ diff --git a/docs/backends/generic-sql.rst b/docs/backends/generic-sql.rst index 09f049c2217e..95b7914a37bd 100644 --- a/docs/backends/generic-sql.rst +++ b/docs/backends/generic-sql.rst @@ -123,7 +123,7 @@ Rules for filling out DNSSEC fields ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. 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 @@ -282,11 +282,12 @@ Domain and zone manipulation :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 @@ -344,7 +345,7 @@ For listing/modifying comments. - ``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 diff --git a/docs/backends/geoip.rst b/docs/backends/geoip.rst index 8dccea036c36..539d16767fa4 100644 --- a/docs/backends/geoip.rst +++ b/docs/backends/geoip.rst @@ -14,7 +14,7 @@ GeoIP backend 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 diff --git a/docs/backends/ldap.rst b/docs/backends/ldap.rst index a1e2045650bc..bc7616b538a2 100644 --- a/docs/backends/ldap.rst +++ b/docs/backends/ldap.rst @@ -124,7 +124,7 @@ password, or "gssapi", which requires a Kerberos keytab. (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: @@ -132,7 +132,7 @@ be used, if the LDAP server doesn't support anonymous binds and with the ^^^^^^^^^^^^^^^ (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: @@ -140,9 +140,9 @@ by ldap-binddn. Only used when "bindmethod" is "simple". ^^^^^^^^^^^^^^^^^^^^ (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: diff --git a/docs/backends/lmdb.rst b/docs/backends/lmdb.rst index db573f447b55..ffde491f6bdb 100644 --- a/docs/backends/lmdb.rst +++ b/docs/backends/lmdb.rst @@ -43,7 +43,7 @@ Path to the LMDB file (e.g. */var/lib/powerdns/pdns.lmdb*) ``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: @@ -55,11 +55,10 @@ Default is 2 on 32 bits systems, and 64 on 64 bits systems. ``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. @@ -77,9 +76,9 @@ Default is 2 on 32 bits systems, and 64 on 64 bits systems. ``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 diff --git a/docs/backends/remote.rst b/docs/backends/remote.rst index 33fba2e59641..d2e6f62ed5d4 100644 --- a/docs/backends/remote.rst +++ b/docs/backends/remote.rst @@ -20,8 +20,8 @@ Important notices ----------------- 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 @@ -231,7 +231,7 @@ Response: ``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. @@ -329,7 +329,7 @@ Response: ~~~~~~~~~~~~~~~~~~~~~~~~ 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 @@ -374,7 +374,7 @@ Response: 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 diff --git a/docs/backends/tinydns.rst b/docs/backends/tinydns.rst index 8e65e836e628..9ab90282e7b8 100644 --- a/docs/backends/tinydns.rst +++ b/docs/backends/tinydns.rst @@ -12,9 +12,9 @@ TinyDNS Backend - Launch: ``tinydns`` The TinyDNS backend allows you to use -`djbdns's `__ ``data.cdb`` file format as +`djbdns's `__ ``data.cdb`` file format as the storage of your DNS records. The ``data.cdb`` file is created using -`tinydns-data `__. The backend +`tinydns-data `__. The backend is designed to be able to use the ``data.cdb`` files without any changes. @@ -42,11 +42,11 @@ Specifies the name of the data file to use. - Integer - Default: 11 -This adjusts the `TAI `__ value if timestamps are -used. These seconds will be added to the start point (1970) and will -allow you to adjust for leap seconds. The current default is 11. The -last update was on `june 30th -2012 `__. +This adjusts the `TAI `__ value if +timestamps are used. These seconds will be added to the start point (1970) +and will allow you to adjust for leap seconds. The current default is 11. +The last update was on `January 1st, +2017 `__. .. _setting-tinydns-notify-on-startup: @@ -116,7 +116,7 @@ domains or updated serial numbers. The CDB datafile requires us to do a full scan of all the records. When running with verbose logging, this could lead to a lot of output. The scanning of the CDB file may also take a while on systems with large files. The scan happens at an -interval set by the :ref:`setting-slave-cycle-interval`. It +interval set by the :ref:`setting-xfr-cycle-interval`. It might be useful to raise this value to limit the amount of scans on the CDB file. @@ -130,17 +130,17 @@ Useful implementation Notes This backend might solve some issues you have with the current tinydns noted on `Jonathan de Boyne -Pollard's `__ +Pollard's `__ `djbdns known problems -page `__. +page `__. The ``data.cdb`` file format support all types of records. They are sometimes difficult to create because you need to specify the actual content of the rdata. `Tinydns.org `__ provides a number of links to tools/cgi-scripts that allow you to create records. -`Anders Brownworth `__ also provides a number of +`Anders Brownworth `__ also provides a number of useful record building scripts on his -`djbdnsRecordBuilder `__. +`djbdnsRecordBuilder `__. PowerDNS and TinyDNS handle wildcards differently. Looking up foo.www.example.com with the below records on TinyDNS will return diff --git a/docs/catalog.rst b/docs/catalog.rst index 279009ae9e46..e641f77a687f 100644 --- a/docs/catalog.rst +++ b/docs/catalog.rst @@ -41,7 +41,7 @@ None really. 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 ~~~~~~~~~~~~ diff --git a/docs/common/secpoll.rst b/docs/common/secpoll.rst index a9eee744afd9..3e52fd8d969b 100644 --- a/docs/common/secpoll.rst +++ b/docs/common/secpoll.rst @@ -15,7 +15,7 @@ To enable distributors of PowerDNS to signal that they have backported versions, 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. diff --git a/docs/dnssec/advice.rst b/docs/dnssec/advice.rst index f43b1741e0fd..af015580871c 100644 --- a/docs/dnssec/advice.rst +++ b/docs/dnssec/advice.rst @@ -15,9 +15,9 @@ to the keying defaults of ``pdnsutil secure-zone``. It is possible to operate a zone with different keying algorithms simultaneously, but it has also been observed that this is not reliable. -Depending on your master/slave setup, you may need to tinker with the -:ref:`SOA-EDIT ` metadata on your master. -This is described in the :ref:`soa-edit-ensure-signature-freshness-on-slaves` section. +Depending on your primary/secondary setup, you may need to tinker with the +:ref:`SOA-EDIT ` metadata on your primary. +This is described in the :ref:`soa-edit-ensure-signature-freshness-on-secondaries` section. Packet sizes, fragments, TCP/IP service --------------------------------------- diff --git a/docs/dnssec/migration.rst b/docs/dnssec/migration.rst index 0ba6656c8716..9217cc4a3425 100644 --- a/docs/dnssec/migration.rst +++ b/docs/dnssec/migration.rst @@ -29,7 +29,7 @@ To deliver a correctly signed zone with the :ref:`dnssec-pdnsutil-dnssec-default pdnsutil secure-zone ZONE To view the DS records for this zone (to transfer to the parent zone), -run +run: .. code-block:: shell diff --git a/docs/dnssec/modes-of-operation.rst b/docs/dnssec/modes-of-operation.rst index fd06f5ddaa92..ad7ae6657b10 100644 --- a/docs/dnssec/modes-of-operation.rst +++ b/docs/dnssec/modes-of-operation.rst @@ -138,8 +138,8 @@ Pre-signed records ------------------ In this mode, PowerDNS serves zones that already contain DNSSEC records. -Such zones can either be slaved from a remote master in online signing -mode, or can be pre-signed using tools like OpenDNSSEC, ldns-signzone, +Such zones can either be served as secondary from a remote primary in online +signing mode, or can be pre-signed using tools like OpenDNSSEC, ldns-signzone, and dnssec-signzone. Even in this mode, PowerDNS will synthesize NSEC(3) records itself @@ -150,10 +150,10 @@ Front-signing ------------- As a special feature, PowerDNS can operate as a signing server which -operates as a slave to an unsigned master. +operates as a secondary to an unsigned primary. In this way, if keying material is available for an unsigned zone that -is retrieved from a master server, this keying material will be used +is retrieved from a primary server, this keying material will be used when serving data from this zone. As part of the zone retrieval, the equivalent of @@ -163,10 +163,10 @@ fields are set correctly in the backend. Signed AXFR ----------- -An outgoing zone transfer from a signing master contains all information +An outgoing zone transfer from a signing primary contains all information required for the receiving party to rectify the zone without knowing the keys, such as signed NSEC3 records for empty non-terminals. The zone is -not required to be rectified on the master. +not required to be rectified on the primary. The signing and hashing algorithms are described in :ref:`dnssec-online-signing`. diff --git a/docs/dnssec/operational.rst b/docs/dnssec/operational.rst index a2de3b928d8e..34d597855a9b 100644 --- a/docs/dnssec/operational.rst +++ b/docs/dnssec/operational.rst @@ -47,7 +47,7 @@ e.g. pdnsutil set-nsec3 example.net '1 0 0 -' The quoted part is the content of the NSEC3PARAM records, as defined in -:rfc:`5155 <5155#section-4>`, in order: +:rfc:`RFC 5155 <5155#section-4>`, in order: - Hash algorithm, should always be ``1`` (SHA1) - Flags, set to ``1`` for :rfc:`NSEC3 Opt-out <5155#section-6>`, this best @@ -71,15 +71,15 @@ To convert a zone from NSEC3 to NSEC operations, run: for zones with algorithm 5 (RSASHA1), 6 (DSA-NSEC3-SHA1) or 7 (RSASHA1-NSEC3-SHA1). -.. _soa-edit-ensure-signature-freshness-on-slaves: +.. _soa-edit-ensure-signature-freshness-on-secondaries: -SOA-EDIT: ensure signature freshness on slaves ----------------------------------------------- +SOA-EDIT: ensure signature freshness on secondaries +--------------------------------------------------- -As RRSIGs can expire, slave servers need to know when to re-transfer the +As RRSIGs can expire, secondary servers need to know when to re-transfer the zone. In most implementations (BIND, NSD), this is done by re-signing the full zone outside of the nameserver, increasing the SOA serial and -serving the new zone on the master. +serving the new zone on the primary. With PowerDNS in Live-signing mode, the SOA serial is not increased by default when the RRSIG dates are rolled. @@ -87,14 +87,14 @@ default when the RRSIG dates are rolled. For zones that use :ref:`native-operation` replication PowerDNS will serve valid RRSIGs on all servers. -For :ref:`master ` zones (where -replication happens by means of AXFR), PowerDNS slaves will +For :ref:`primary ` zones (where +replication happens by means of AXFR), PowerDNS secondaries will automatically re-transfer the zone when it notices the RRSIGs have changed, even when the SOA serial is not increased. This ensures the zone never serves old signatures. -If your DNS setup uses non-PowerDNS slaves, the slaves need to know when -the signatures have been updated. This can be accomplished by setting +If your DNS setup uses non-PowerDNS secondaries, the secondaries need to know +when the signatures have been updated. This can be accomplished by setting the :ref:`metadata-soa-edit` metadata for DNSSEC signed zones. This value controls how the value of the SOA serial is modified by PowerDNS. @@ -159,10 +159,10 @@ EPOCH Sets the SOA serial to the number of seconds since the epoch. .. warning:: - Don't combine this with AXFR - the slaves would keep + Don't combine this with AXFR - the secondaries would keep refreshing all the time. If you need fast updates, sync the backend databases directly with incremental updates (or use the same database - server on the slaves) + server on the secondaries) NONE ^^^^ @@ -183,10 +183,10 @@ In some settings, having such (private) keying material available online is considered undesirable. In this case, consider running in pre-signed mode. -A slightly more complex approach is running a *hidden* master in simple +A slightly more complex approach is running a *hidden* primary in simple online signing mode, but on a highly secured system unreachable for the -public. Internet-connected slaves can then transfer the zones pre-signed -from this master over a secure private network. This topology offers +public. Internet-connected secondaries can then transfer the zones pre-signed +from this primary over a secure private network. This topology offers substantial security benefits with regards to key material while maintaining ease of daily operation by PowerDNS's features in online mode. @@ -220,5 +220,7 @@ Note that the NSEC/NSEC3 records proving those negatives will get the high TTL i This behaviour was changed in version 4.3.0. We believe the language in RFC 4034 and 5155 about the NSEC(3) TTL is a mistake, and we have chosen to honour its spirit instead of its words. + This unfortunate wording was eventually corrected in :rfc:`RFC 9077 <9077#section-3>`. + NSEC(3) records now get the negative TTL (which is the lowest of the SOA TTL and the SOA minimum), which means their TTL matches that of an error such as NXDOMAIN. - The warning about RFC8198 no longer applies. + This conforms to RFC9077. diff --git a/docs/dnssec/pkcs11.rst b/docs/dnssec/pkcs11.rst index b1f95f1ba0a8..7f5164bd0a97 100644 --- a/docs/dnssec/pkcs11.rst +++ b/docs/dnssec/pkcs11.rst @@ -174,4 +174,4 @@ Smart Card token on Ubuntu 14.04. pdnsutil show-zone zone - Note that the physical token is pretty slow, so you have to use it as - hidden master. It has been observed to produce about 1.5 signatures/second. + hidden primary. It has been observed to produce about 1.5 signatures/second. diff --git a/docs/dnsupdate.rst b/docs/dnsupdate.rst index f41c45351b98..de604c8b344f 100644 --- a/docs/dnsupdate.rst +++ b/docs/dnsupdate.rst @@ -275,9 +275,9 @@ Kdhcpdupdate.*.private). You're interested in the .key file: 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: :: @@ -338,10 +338,10 @@ configuration file. 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 @@ -351,10 +351,10 @@ the following to the PowerDNS configuration file (pdns.conf). 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 diff --git a/docs/domainmetadata.rst b/docs/domainmetadata.rst index 5f399037822b..940770a92253 100644 --- a/docs/domainmetadata.rst +++ b/docs/domainmetadata.rst @@ -37,7 +37,7 @@ ALLOW-AXFR-FROM 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: @@ -194,9 +194,9 @@ SLAVE-RENOTIFY -------------- .. 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. +the :ref:`setting-secondary-do-renotify` setting. .. _metadata-soa-edit: @@ -204,9 +204,9 @@ SOA-EDIT -------- 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 ` +documentation ` for more information. .. _metadata-soa-edit-api: @@ -231,7 +231,7 @@ TSIG-ALLOW-DNSUPDATE -------------------- This setting allows you to set the TSIG key required to do an :doc:`dnsupdate`. -If :ref:`GSS-TSIG ` is enabled, you can put kerberos principals here as well. +If :ref:`GSS-TSIG ` is enabled, you can put Kerberos principals here as well. Extra metadata -------------- diff --git a/docs/guides/basic-database.rst b/docs/guides/basic-database.rst index 15afac0091a2..233518b6b176 100644 --- a/docs/guides/basic-database.rst +++ b/docs/guides/basic-database.rst @@ -90,9 +90,9 @@ If we now requery our database, ``www.example.com`` should be present:: 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. diff --git a/docs/http-api/index.rst b/docs/http-api/index.rst index d2e56e7538d9..100a48a7ce03 100644 --- a/docs/http-api/index.rst +++ b/docs/http-api/index.rst @@ -283,9 +283,7 @@ A simple ``GET`` request will return a response similar to the following: pdns_auth_user_msec 48 -Prometheus can then be configured to scrape metrics from this endpoint using a simple job description like the following: - -.. prometheus scrape-job:: +Prometheus can then be configured to scrape metrics from this endpoint using a simple job description like the following:: scrape_configs: - job_name: 'pdns_auth' @@ -300,7 +298,7 @@ Enabling the API ---------------- To enable the API, the webserver and the HTTP API need to be enabled. -Add these lines to the ``pdns.conf``:: +Add these lines to ``pdns.conf``:: api=yes api-key=changeme @@ -331,7 +329,7 @@ Response code ``4xx`` or ``5xx``, depending on the situation. - Invalid JSON body from client: ``400 Bad Request`` - Input validation failed: ``422 Unprocessable Entity`` -- JSON body from client not a hash: ``400 Bad Request`` +- JSON body from client is not a hash: ``400 Bad Request`` Error responses have a JSON body of this format: @@ -345,7 +343,7 @@ The API accepts and emits :rfc:`JSON <7159>`. The ``Accept:`` header determines the output format. An unknown value or ``*/*`` will cause a ``400 Bad Request``. -All text is UTF-8 and HTTP headers will reflect this. +All text is encoded in UTF-8 and HTTP headers will reflect this. Data types: diff --git a/docs/lua-records/functions.rst b/docs/lua-records/functions.rst index 45af5dde9a4f..f6bde0bdf759 100644 --- a/docs/lua-records/functions.rst +++ b/docs/lua-records/functions.rst @@ -216,12 +216,13 @@ Record creation functions :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:: @@ -364,7 +365,7 @@ Reverse DNS functions 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) @@ -426,7 +427,7 @@ Reverse DNS functions $ 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]) diff --git a/docs/lua-records/index.rst b/docs/lua-records/index.rst index 3da00b29ea07..355c31ebc93d 100644 --- a/docs/lua-records/index.rst +++ b/docs/lua-records/index.rst @@ -235,7 +235,7 @@ Shared Lua state model 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. diff --git a/docs/lua-records/reference/comboaddress.rst b/docs/lua-records/reference/comboaddress.rst index 719a9f25cb08..d851271480a3 100644 --- a/docs/lua-records/reference/comboaddress.rst +++ b/docs/lua-records/reference/comboaddress.rst @@ -104,12 +104,14 @@ Functions and methods of a ``ComboAddressSet`` 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 diff --git a/docs/lua-records/reference/dnsheader.rst b/docs/lua-records/reference/dnsheader.rst index 125de29bc652..4d438f622714 100644 --- a/docs/lua-records/reference/dnsheader.rst +++ b/docs/lua-records/reference/dnsheader.rst @@ -29,7 +29,7 @@ DNSHeader (``dh``) object .. method:: DNSHeader:getAD() -> bool - Authenticated data from named + Authenticated data from name server .. method:: DNSHeader:getAA() -> bool diff --git a/docs/lua-records/reference/dnsresourcerecord.rst b/docs/lua-records/reference/dnsresourcerecord.rst index a0810e444de0..658e391c3246 100644 --- a/docs/lua-records/reference/dnsresourcerecord.rst +++ b/docs/lua-records/reference/dnsresourcerecord.rst @@ -15,14 +15,13 @@ Functions and methods of a ``DNSResourceRecord`` .. 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 @@ -52,7 +51,7 @@ Functions and methods of a ``DNSResourceRecord`` .. method:: DNSResourceRecord:lastModified() -> int - If unzero, last time this record was changed + If non-zero, last time this record was changed .. method:: DNSResourceRecord:ttl() -> int diff --git a/docs/lua-records/reference/misc.rst b/docs/lua-records/reference/misc.rst index ab85b23f892e..70cc12c91303 100644 --- a/docs/lua-records/reference/misc.rst +++ b/docs/lua-records/reference/misc.rst @@ -16,10 +16,10 @@ Other functions - `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]) diff --git a/docs/lua-records/reference/netmask.rst b/docs/lua-records/reference/netmask.rst index 8c248c4283e7..a777982f6870 100644 --- a/docs/lua-records/reference/netmask.rst +++ b/docs/lua-records/reference/netmask.rst @@ -118,7 +118,7 @@ Prefixing a mask with ``!`` excludes that mask from matching. Adds ``masks`` to the NetMaskGroup. - :param {str} mask: The masks to add. + :param {str} masks: The masks to add. .. method:: NetMaskGroup:match(address) -> bool diff --git a/docs/manpages/calidns.1.rst b/docs/manpages/calidns.1.rst index 8ec977b8c825..27e68e9554d9 100644 --- a/docs/manpages/calidns.1.rst +++ b/docs/manpages/calidns.1.rst @@ -44,5 +44,5 @@ Options in percent. --plot-file Write results to the specified file. --quiet Whether to run quietly, outputting only the maximum QPS reached. - This option is mostly useful when used with --minimum-success-rate. + This option is mostly useful when used with ``--minimum-success-rate``. --want-recursion Set this flag to send queries with the Recursion Desired flag set. diff --git a/docs/manpages/dnsbulktest.1.rst b/docs/manpages/dnsbulktest.1.rst index fce6b236b699..c3e5f225c28f 100644 --- a/docs/manpages/dnsbulktest.1.rst +++ b/docs/manpages/dnsbulktest.1.rst @@ -11,7 +11,7 @@ Description :program:`dnsbulktest` sends a large amount of different queries (for up to *LIMIT* different domains) to the nameserver at *IPADDRESS* on port -*PORT*. It reads the domain names from STDIN in the alexa topX format +*PORT*. It reads the domain names from STDIN in the Alexa topX format and outputs statistics on STDOUT. Options diff --git a/docs/manpages/dnspcap2calidns.1.rst b/docs/manpages/dnspcap2calidns.1.rst index f85f724a7bda..91f1ac60a63d 100644 --- a/docs/manpages/dnspcap2calidns.1.rst +++ b/docs/manpages/dnspcap2calidns.1.rst @@ -10,7 +10,7 @@ Description ----------- :program:`dnspcap2calidns` reads the PCAP file *PCAPFILE* for DNS queries and -writes these to *OUTFILE* in the format understood by :program:`calidns` +writes these to *OUTFILE* in the format understood by :program:`calidns`. Options ------- diff --git a/docs/manpages/dnsreplay.1.rst b/docs/manpages/dnsreplay.1.rst index 86354980626c..12633281240e 100644 --- a/docs/manpages/dnsreplay.1.rst +++ b/docs/manpages/dnsreplay.1.rst @@ -13,10 +13,10 @@ This program takes recorded questions and answers and replays them to the specified nameserver and reporting afterwards which percentage of answers matched, were worse or better. -dnsreplay compares the answers and some other metrics with the actual +:program:`dnsreplay` compares the answers and some other metrics with the actual ones with those found in the dumpfile. -By default it only replay queries with recursion-desired flag set. +By default it will only replay queries with recursion-desired flag set. Options ------- @@ -36,11 +36,11 @@ PORT --packet-limit Stop after replaying *NUM* packets. Default for *NUM* is 0, which means no limit. --pcap-dns-port Look at packets from or to this port in the PCAP. Default is 53. ---quiet If *FLAG* is set to 1. dnsreplay will not be very noisy with its +--quiet If *FLAG* is set to 1, :program:`dnsreplay` will not be very noisy with its output. This is the default. ---recursive If *FLAG* is set to 1. dnsreplay will only replay queries with +--recursive If *FLAG* is set to 1, :program:`dnsreplay` will only replay queries with recursion desired flag set. This is the default. ---source-from-pcap If *FLAG* is set to 1. dnsreplay will send the replayed queries from the +--source-from-pcap If *FLAG* is set to 1, :program:`dnsreplay` will send the replayed queries from the source IP address and port present in the PCAP file. This requires IP_TRANSPARENT support. Default is 0 which means replayed queries will be sent from a local address. diff --git a/docs/manpages/dnstcpbench.1.rst b/docs/manpages/dnstcpbench.1.rst index c5b18f237111..2bcbe4644512 100644 --- a/docs/manpages/dnstcpbench.1.rst +++ b/docs/manpages/dnstcpbench.1.rst @@ -35,16 +35,17 @@ The equivalent for IPv6 is not known. Options ------- --f, , --file *FILENAME* from which to read queries. Defaults to standard input if unspecified. --h, --help Provide a helpful message. ---timeout-msec *MSEC* milliseconds to wait for an answer. --u, --udp-first Attempt resolution via UDP first, only do TCP if truncated answer is received. --v, --verbose Be wordy on what the program is doing. ---workers Use *NUM* parallel worker threads. - -*REMOTE-ADDRESS*: IPv4 or IPv6 to test against. - -*REMOTE-PORT*: Port to test against, defaults to 53. +REMOTE-ADDRESS + IPv4 or IPv6 to test against. +REMOTE-PORT + Port to test against, defaults to 53. + +-f , --file *FILENAME* from which to read queries. Defaults to standard input if unspecified. +-h, --help Provide a helpful message. +--timeout-msec *MSEC* milliseconds to wait for an answer. +-u, --udp-first Attempt resolution via UDP first, only do TCP if truncated answer is received. +-v, --verbose Be wordy on what the program is doing. +--workers Use *NUM* parallel worker threads. Bugs ---- diff --git a/docs/manpages/dnswasher.1.rst b/docs/manpages/dnswasher.1.rst index 1b20806226cf..57dea35bbf70 100644 --- a/docs/manpages/dnswasher.1.rst +++ b/docs/manpages/dnswasher.1.rst @@ -4,12 +4,12 @@ dnswasher Synopsis -------- -:program:`dnswasher` *INFILE* [*INFILE*] *OUTFILE* +:program:`dnswasher` [*OPTION*]... *INFILE* [*INFILE*] *OUTFILE* Description ----------- -dnswasher takes one or more *INFILE*\ s in PCAP format and writes out +:program:`dnswasher` takes one or more *INFILE*\ s in PCAP format and writes out *OUTFILE* also in PCAP format, while obfuscating end-user IP addresses. This is useful to share data with third parties while attempting to @@ -25,11 +25,11 @@ about. Options ------- ---decrypt,-d Undo IPCipher encryption of IP addresses ---help, -h Show summary of options. ---key,-k Base64 encoded 128-bit key for IPCipher ---passphrase,-p Passphrase that will be used to derive an IPCipher key ---version,-v Output version +--decrypt, -d Undo IPCipher encryption of IP addresses. +--help, -h Show summary of options. +--key, -k Base64 encoded 128-bit key for IPCipher. +--passphrase, -p Passphrase that will be used to derive an IPCipher key. +--version, -v Output version. See also -------- diff --git a/docs/manpages/ixplore.1.rst b/docs/manpages/ixplore.1.rst index 1fb08b2f6720..dd935fbad106 100644 --- a/docs/manpages/ixplore.1.rst +++ b/docs/manpages/ixplore.1.rst @@ -35,7 +35,7 @@ ZONE The name of the zone the IXFRs are consumed from. BEFORE Path to the 'before' zonefile. -AFYER +AFTER Path to the 'after' zonefile. track-mode diff --git a/docs/manpages/pdns_control.1.rst b/docs/manpages/pdns_control.1.rst index 032cb8ef7254..17ce3a0b5868 100644 --- a/docs/manpages/pdns_control.1.rst +++ b/docs/manpages/pdns_control.1.rst @@ -39,7 +39,7 @@ bind-domain-extended-status [*ZONE*...] Output an extended status of all zones, containing much more information than the simple zone status, like the number of records currently loaded, whether pdns -is primary or secondary for the zone, the list of primaries, various timers, etc +is primary or secondary for the zone, the list of primaries, various timers, etc. Optionally, append *ZONE*\ s to get the status of specific zones. bind-domain-status [*ZONE*...] @@ -66,7 +66,7 @@ Show the content of the cache. current-config [diff] ^^^^^^^^^^^^^^^^^^^^^ -Show the currently running configuration. The output has the same format as ``pdns_server --config``. With the diff option only modified options are included in the output. +Show the currently running configuration. The output has the same format as ``pdns_server --config``. With the diff option, only modified options are included in the output. cycle ^^^^^ @@ -118,7 +118,7 @@ specified the entire cache is purged. qtypes ^^^^^^ -Get a count of queries per qtype on standard out. +Get a count of queries per qtype on standard output. quit ^^^^ diff --git a/docs/manpages/pdns_server.1.rst b/docs/manpages/pdns_server.1.rst index 9ee765ae1541..b383a509b7f1 100644 --- a/docs/manpages/pdns_server.1.rst +++ b/docs/manpages/pdns_server.1.rst @@ -17,21 +17,22 @@ documentation for more information. Options ------- -See the online documentation for all options +See the online documentation for all options. The most important ones are: --daemon Indicate if the server should run in the background as a real daemon, or in the foreground. --guardian Run :program:`pdns_server` inside a guardian. This guardian monitors the performance of the inner :program:`pdns_server` instance. It is also this - guardian that :program:`pdns_control`\ talks to. + guardian that :program:`pdns_control` talks to. --control-console Run the server in a special monitor mode. This enables detailed logging and exposes the raw control socket. --loglevel= Set the logging level. --config Show the currently configuration. There are three optional values: - --config=default show the default configuration. - --config=diff show modified options in the current configuration. - --config=check parse the current configuration, with error checking. ---help To view more options that are available use this program. + + --config=default show the default configuration. + --config=diff show modified options in the current configuration. + --config=check parse the current configuration, with error checking. +--help Display the list of all the available options. See also -------- diff --git a/docs/manpages/pdnsutil.1.rst b/docs/manpages/pdnsutil.1.rst index dfc8e01c6030..3ddfcc218b87 100644 --- a/docs/manpages/pdnsutil.1.rst +++ b/docs/manpages/pdnsutil.1.rst @@ -24,13 +24,13 @@ Options --config-name Virtual configuration name --config-dir Location of pdns.conf. Default is /etc/powerdns. -COMMANDS +Commands -------- There are many available commands, this section splits them up into -their respective uses +their respective uses. -DNSSEC RELATED COMMANDS +DNSSEC-related Commands ----------------------- Several commands manipulate the DNSSEC keys and options for zones. Some @@ -103,12 +103,13 @@ set-nsec3 *ZONE* ['*HASH-ALGORITHM* *FLAGS* *ITERATIONS* *SALT*'] [**narrow**] NSEC3 records are created. The NSEC3 parameters must be quoted on the command line. *HASH-ALGORITHM* must be 1 (SHA-1). Setting *FLAGS* to 1 enables NSEC3 opt-out operation. Only do this if you - know you need it. For *ITERATIONS*, please consult RFC 5155, section - 10.3. And be aware that a high number might overload validating + know you need it. For *ITERATIONS*, please consult + :rfc:`RFC 5155<5155#section-10.3>`. + And be aware that a high number might overload validating resolvers and that a limit can be set with ``max-nsec3-iterations`` in ``pdns.conf``. The *SALT* is a hexadecimal string encoding the bits for the salt, or - to use no salt. Setting **narrow** will make PowerDNS - send out "white lies" (RFC 7129) about the next secure record to + send out "white lies" (:rfc:`7129`) about the next secure record to prevent zone enumeration. Instead of looking it up in the database, it will send out the hash + 1 as the next secure record. Narrow mode requires online signing capabilities by the nameserver and therefore diff --git a/docs/manpages/zone2json.1.rst b/docs/manpages/zone2json.1.rst index b9c9d3ff1dae..850388a6e05a 100644 --- a/docs/manpages/zone2json.1.rst +++ b/docs/manpages/zone2json.1.rst @@ -10,7 +10,7 @@ Description ----------- :program:`zone2json` parses BIND named.conf files and zonefiles and outputs -JSON on standard out, which can then be fed to the PowerDNS API. +JSON on standard output, which can then be fed to the PowerDNS API. :program:`zone2json` understands the BIND master file extension ``$GENERATE`` and will also honour ``$ORIGIN`` and ``$TTL``. diff --git a/docs/manpages/zone2sql.1.rst b/docs/manpages/zone2sql.1.rst index 92beab49c544..c177bae8de33 100644 --- a/docs/manpages/zone2sql.1.rst +++ b/docs/manpages/zone2sql.1.rst @@ -10,7 +10,7 @@ Description ----------- :program:`zone2sql` parses BIND named.conf files and zonefiles and outputs SQL -on standard out, which can then be fed to your database. +on standard output, which can then be fed to your database. :program:`zone2sql` understands the BIND master file extension ``$GENERATE`` and will also honour ``$ORIGIN`` and ``$TTL``. diff --git a/docs/migration.rst b/docs/migration.rst index 55786b4c9471..737cec906184 100644 --- a/docs/migration.rst +++ b/docs/migration.rst @@ -15,14 +15,14 @@ Using AXFR to a Slave-Capable Backend The easiest way to migrate all your zones from your old infrastructure to PowerDNS is to add all your domains as a slave domain with your current master as the master, wait for the zones to be transferred and -change the zones to master. Make sure :ref:`setting-slave` is set to "yes" +change the zones to master. Make sure :ref:`setting-secondary` is set to "yes" in your pdns.conf. To A Generic SQL Backend ~~~~~~~~~~~~~~~~~~~~~~~~ .. 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 @@ -40,7 +40,7 @@ domain in the database: UPDATE domains set type='MASTER' where type='SLAVE'; -And set :ref:`setting-master` to "yes" in your pdns.conf +And set :ref:`setting-primary` to "yes" in your pdns.conf and restart PowerDNS. Or, if you want to use :ref:`native `: @@ -76,7 +76,7 @@ transferred. Now you can change the zone type to master: file "/var/lib/powerdns/zones/example.net.zone"; }; -Don't forget to enable :ref:`setting-master` in your +Don't forget to enable :ref:`setting-primary` in your pdns.conf and restart, or if this setting was already set, use ``pdns_control rediscover`` to load these zones as master zones. @@ -103,7 +103,7 @@ Using ``zone2sql`` ^^^^^^^^^^^^^^^^^^ To migrate, the ``zone2sql`` tool is provided. This tool parses a BIND -``named.conf`` file and zone files and outputs SQL on standard out, +``named.conf`` file and zone files and outputs SQL on standard output, which can then be fed to your database. It understands the BIND master file extension ``$GENERATE`` and will also honour ``$ORIGIN`` and ``$TTL``. diff --git a/docs/modes-of-operation.rst b/docs/modes-of-operation.rst index 6f563a43a82b..0d7bffef98ed 100644 --- a/docs/modes-of-operation.rst +++ b/docs/modes-of-operation.rst @@ -269,10 +269,12 @@ AXFR zone transfer. The user-defined function ``axfrfilter`` within your 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:: @@ -291,7 +293,7 @@ If your function decides to handle a resource record it must return a 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. @@ -302,7 +304,7 @@ Consider the following simple example: 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] = { diff --git a/docs/performance.rst b/docs/performance.rst index cc2a473621d8..2bcd975a046a 100644 --- a/docs/performance.rst +++ b/docs/performance.rst @@ -122,7 +122,7 @@ defaults to 20 seconds. 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 @@ -321,6 +321,12 @@ security-status ^^^^^^^^^^^^^^^ 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 @@ -405,12 +411,6 @@ timedout-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 diff --git a/docs/tsig.rst b/docs/tsig.rst index 197f50fa41ed..6335e96c2c09 100644 --- a/docs/tsig.rst +++ b/docs/tsig.rst @@ -14,8 +14,8 @@ algorithms are 'hmac-sha1', 'hmac-shaX' where X is 224, 256, 384 or 512. 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``)! @@ -134,7 +134,7 @@ Prerequisites 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