From: Miod Vallat Date: Thu, 26 Jun 2025 15:25:19 +0000 (+0200) Subject: Update documentation to reflect new pdnsutil syntax. X-Git-Tag: rec-5.4.0-alpha0~14^2~5 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=eb61969d2a2ad3541450ce9b5b2646e89c1ee683;p=thirdparty%2Fpdns.git Update documentation to reflect new pdnsutil syntax. Add an old-to-new command table to the 5.0 upgrade notes. Signed-off-by: Miod Vallat --- diff --git a/docs/appendices/backend-writers-guide.rst b/docs/appendices/backend-writers-guide.rst index c0ec5dfdf3..799638ae4d 100644 --- a/docs/appendices/backend-writers-guide.rst +++ b/docs/appendices/backend-writers-guide.rst @@ -166,7 +166,7 @@ furthermore, only about its A record: bool list(const string &target, domainid_t id) { - return false; // we don't support pdnsutil list-zone or AXFR + return false; // we don't support pdnsutil zone list or AXFR } void lookup(const QType &type, const string &qdomain, domainid_t zoneId, DNSPacket *p) @@ -353,7 +353,7 @@ Methods the backend. The currently used capabilities are: * `CAP_DNSSEC` Backend implements :ref:`backend-dnssec`. -* `CAP_LIST` Backend implements `list`, for AXFR or `pdnsutil list-zone` +* `CAP_LIST` Backend implements `list`, for AXFR or `pdnsutil zone list` .. cpp:function:: void DNSBackend::lookup(const QType &qtype, const string &qdomain, domainid_t zoneId, DNSPacket *pkt=nullptr) @@ -928,7 +928,7 @@ contain `CAP_DNSSEC` if that backend supports DNSSEC. .. cpp:function:: virtual bool feedEnts(domainid_t domain_id, map &nonterm) - This method is used by ``pdnsutil rectify-zone`` to populate missing non-terminals. This is used when you have, say, record like _sip._upd.example.com, but no _udp.example.com. PowerDNS requires that there exists a non-terminal in between, and this instructs you to add one. + This method is used by ``pdnsutil zone rectify`` to populate missing non-terminals. This is used when you have, say, record like _sip._upd.example.com, but no _udp.example.com. PowerDNS requires that there exists a non-terminal in between, and this instructs you to add one. .. cpp:function:: virtual bool feedEnts3(domainid_t domain_id, const DNSName &domain, map &nonterm, const NSEC3PARAMRecordContent& ns3prc, bool narrow) diff --git a/docs/appendices/types.rst b/docs/appendices/types.rst index f74f5f7202..6747785592 100644 --- a/docs/appendices/types.rst +++ b/docs/appendices/types.rst @@ -9,7 +9,7 @@ grouped. Host names and the MNAME of a SOA records are NEVER terminated with a '.' in PowerDNS storage! If a trailing '.' is present it will inevitably cause problems, problems that may be hard to debug. - Use ``pdnsutil check-zone`` to validate your zone data. + Use ``pdnsutil zone check`` to validate your zone data. .. note:: Whenever the storage format is mentioned, this relates only to the way diff --git a/docs/backends/generic-sql.rst b/docs/backends/generic-sql.rst index 44bd82505c..08f9460b18 100644 --- a/docs/backends/generic-sql.rst +++ b/docs/backends/generic-sql.rst @@ -25,9 +25,9 @@ Native operation To add a domain, issue the following:: - pdnsutil create-zone example.com + pdnsutil zone create example.com -Records can now be added using ``pdnsutil add-record`` or ``pdnsutil edit-zone``. +Records can now be added using ``pdnsutil rrset add`` or ``pdnsutil zone edit``. Secondary operation ^^^^^^^^^^^^^^^^^^^ @@ -35,7 +35,7 @@ Secondary operation These backends are fully secondary capable. To become a secondary of the 'example.com' domain, using 198.51.100.6 as the primary execute this:: - pdnsutil create-secondary-zone example.com 198.51.100.6 + pdnsutil zone create-secondary example.com 198.51.100.6 And wait a while for PowerDNS to pick up the addition - which happens within one minute (this is determined by the @@ -64,8 +64,8 @@ seconds by default. PowerDNS has support for multiple primaries per zone, and also port numbers for these primaries:: - pdnsutil create-secondary-zone example.com 198.51.100.6 2001:0DB8:15:4AF::4 - pdnsutil create-secondary-zone example.net 198.51.100.20:5301 '[2001:0DB8:11:6E::4]:54' + pdnsutil zone create secondary example.com 198.51.100.6 2001:0DB8:15:4AF::4 + pdnsutil zone create secondary example.net 198.51.100.20:5301 '[2001:0DB8:11:6E::4]:54' Autoprimary operation ^^^^^^^^^^^^^^^^^^^^^ @@ -73,7 +73,7 @@ Autoprimary operation To configure a :ref:`autoprimary ` with IP address 203.0.113.53 which lists this installation as 'autosecondary.example.com', issue the following:: - pdnsutil add-autoprimary 203.0.113.53 autosecondary.example.com internal + pdnsutil autoprimary add 203.0.113.53 autosecondary.example.com internal From now on, valid notifies from 203.0.113.53 for which the zone lists an NS record containing 'autosecondary.example.com' will lead to the provisioning of a @@ -88,8 +88,8 @@ of serial changes. Raising the serial number of a domain suffices to trigger PowerDNS to send out notifications. To configure a domain for primary operation instead of the default native replication, issue:: - pdnsutil create-zone example.com - pdnsutil set-kind example.com MASTER + pdnsutil zone create example.com + pdnsutil zone set-kind example.com MASTER .. _generic-sql-disabled-data: @@ -127,7 +127,7 @@ Rules for filling out DNSSEC fields Two additional fields in the 'records' table are important: 'auth' and 'ordername'. These fields are set correctly on an incoming zone -transfer, and also by running ``pdnsutil rectify-zone``. +transfer, and also by running ``pdnsutil zone rectify``. The 'auth' field should be set to '1' for data for which the zone itself is authoritative, which includes the SOA record and its own NS records. @@ -152,7 +152,7 @@ www' as its ordername. In 'NSEC3' non-narrow mode, the ordername should contain a lowercase base32hex encoded representation of the salted & iterated hash of the -full record name. ``pdnsutil hash-zone-record zone record`` can be used +full record name. ``pdnsutil rrset hash zone record`` can be used to calculate this hash. In addition, PowerDNS fully supports empty non-terminals. If you have a @@ -227,7 +227,7 @@ is! DNSSEC queries ^^^^^^^^^^^^^^ -These queries are used by e.g. ``pdnsutil rectify-zone``. Make sure to +These queries are used by e.g. ``pdnsutil zone rectify``. Make sure to read :ref:`rules-for-filling-out-dnssec-fields` if you wish to calculate ordername and auth without using pdns-rectify. diff --git a/docs/backends/lmdb.rst b/docs/backends/lmdb.rst index 9c5e8fd671..2f9702747a 100644 --- a/docs/backends/lmdb.rst +++ b/docs/backends/lmdb.rst @@ -152,4 +152,4 @@ LMDB Structure -------------- PowerDNS will create the database structure, no need to manually create the database schema. -Also, it is not possible to directly query the LMDB DB, so recommendation is to use either the API, or pdnsutil. +Also, it is not possible to directly query the LMDB DB, so recommendation is to use either the API, or :doc:`pdnsutil <../manpages/pdnsutil.1>`. diff --git a/docs/backends/remote.rst b/docs/backends/remote.rst index c95bb38b80..3263ffad52 100644 --- a/docs/backends/remote.rst +++ b/docs/backends/remote.rst @@ -1217,7 +1217,7 @@ Response: ``feedEnts`` ~~~~~~~~~~~~ -This method is used by pdnsutil rectify-zone to populate missing +This method is used by ``pdnsutil zone rectify`` to populate missing non-terminals. This is used when you have, say, record like _sip._upd.example.com, but no _udp.example.com. PowerDNS requires that there exists a non-terminal in between, and this instructs you to diff --git a/docs/catalog.rst b/docs/catalog.rst index 05d88bb2ca..66bbd07804 100644 --- a/docs/catalog.rst +++ b/docs/catalog.rst @@ -89,8 +89,8 @@ Create a producer zone: .. code-block:: shell - pdnsutil load-zone catalog.example ZONEFILE - pdnsutil set-kind catalog.example producer + pdnsutil zone load catalog.example ZONEFILE + pdnsutil zone set-kind catalog.example producer Creating producer zones is supported in the :doc:`API `, using type ``PRODUCER``. @@ -102,8 +102,8 @@ In the example below ``example.com`` is the member and ``catalog.example`` is th .. code-block:: shell - pdnsutil set-catalog example.com catalog.example - pdnsutil set-kind example.com primary + pdnsutil catalog set example.com catalog.example + pdnsutil zone set-kind example.com primary Setting catalog values is supported in the :doc:`API `, by setting the ``catalog`` property in the zone properties. Setting the catalog to an empty ``""`` removes the member zone from the catalog it is in. @@ -116,8 +116,8 @@ PowerDNS currently supports the following properties: .. code-block:: shell - pdnsutil set-option example.com producer coo other-catalog.example - pdnsutil set-option example.com producer group pdns-group-x pdns-group-y + pdnsutil zone set-option example.com producer coo other-catalog.example + pdnsutil zone set-option example.com producer group pdns-group-x pdns-group-y There is also an option to set a specific value for a zone. This is done by setting a the ``unique`` value. This is used to signal a state reset to the consumer. @@ -125,7 +125,7 @@ The value for ``unique`` is a single DNS label. .. code-block:: shell - pdnsutil --config-dir=. --config-name=gmysql set-option test.com producer unique 123 + pdnsutil --config-dir=. --config-name=gmysql zone set-option test.com producer unique 123 Setting options is not yet supported in the API. @@ -137,8 +137,8 @@ The only difference is the type, which is now set to CONSUMER. .. code-block:: shell - pdnsutil create-secondary-zone catalog.example 192.0.2.42 - pdnsutil set-kind catalog.example consumer + pdnsutil zone create-secondary catalog.example 192.0.2.42 + pdnsutil zone set-kind catalog.example consumer Creating consumer zones is supported in the :doc:`API `, using type ``CONSUMER``. @@ -154,7 +154,7 @@ server in order to fully apply the changes. .. code-block:: shell - pdnsutil change-secondary-zone-primary catalog.example 192.0.2.45 + pdnsutil zone change-primary catalog.example 192.0.2.45 pdns_control retrieve catalog.example This will update the primary server contact details in each zone diff --git a/docs/dnssec/advice.rst b/docs/dnssec/advice.rst index af01558087..5d1c4867e4 100644 --- a/docs/dnssec/advice.rst +++ b/docs/dnssec/advice.rst @@ -6,7 +6,7 @@ bewildering array of settings that can be configured. It is easy to (mis)configure DNSSEC in such a way that your domain will not operate reliably, or even, at all. We advise operators to stick -to the keying defaults of ``pdnsutil secure-zone``. +to the keying defaults of ``pdnsutil zone secure``. .. note:: GOST may be more widely available in Russia, because it might diff --git a/docs/dnssec/index.rst b/docs/dnssec/index.rst index 7855c45d3c..625a081518 100644 --- a/docs/dnssec/index.rst +++ b/docs/dnssec/index.rst @@ -21,7 +21,7 @@ As an example, securing an existing zone can be as simple as: .. code-block:: shell - $ pdnsutil secure-zone powerdnssec.org + $ pdnsutil zone secure powerdnssec.org Alternatively, PowerDNS can serve pre-signed zones, without knowledge of private keys. diff --git a/docs/dnssec/migration.rst b/docs/dnssec/migration.rst index f5f3d64328..b4e549a744 100644 --- a/docs/dnssec/migration.rst +++ b/docs/dnssec/migration.rst @@ -19,30 +19,30 @@ all the changes in database schemas as shown in the :doc:`upgrade documentation .. warning:: Once the relevant ``backend-dnssec`` switch has been set, stricter rules apply for filling out the database! The short version is: - run ``pdnsutil rectify-all-zones``, even those not secured with DNSSEC! + run ``pdnsutil zone rectify-all``, even those not secured with DNSSEC! For more information, see the :ref:`generic-sql-handling-dnssec-signed-zones`. To deliver a correctly signed zone with the :ref:`dnssec-pdnsutil-dnssec-defaults`, invoke: .. code-block:: shell - pdnsutil secure-zone ZONE + pdnsutil zone secure ZONE To view the DS records for this zone (to transfer to the parent zone), run: .. code-block:: shell - pdnsutil show-zone ZONE + pdnsutil zone show ZONE For a more traditional setup with a KSK and a ZSK, use the following sequence of commands: .. code-block:: shell - pdnsutil add-zone-key ZONE ksk 2048 active rsasha256 - pdnsutil add-zone-key ZONE zsk 1024 active rsasha256 - pdnsutil add-zone-key ZONE zsk 1024 inactive rsasha256 + pdnsutil zone add-key ZONE ksk 2048 active rsasha256 + pdnsutil zone add-key ZONE zsk 1024 active rsasha256 + pdnsutil zone add-key ZONE zsk 1024 inactive rsasha256 This will add a 2048-bit RSA Key Signing Key and two 1024-bit RSA Zone Signing Keys. One of the ZSKs is inactive and can be rolled to if @@ -65,7 +65,7 @@ without changes. In such cases, signing happens externally to PowerDNS, possibly via OpenDNSSEC, ldns-sign or dnssec-sign. PowerDNS needs to know if a zone should receive DNSSEC processing. To -configure, run ``pdnsutil set-presigned ZONE``. +configure, run ``pdnsutil zone set-presigned ZONE``. If you import presigned zones into your database, please do not import the NSEC or NSEC3 records. PowerDNS will synthesize these itself. @@ -75,7 +75,7 @@ automatically. .. warning:: Right now, you will also need to configure NSEC/NSEC3 settings - for pre-signed zones using ``pdnsutil set-nsec3``. Default is NSEC, in + for pre-signed zones using ``pdnsutil zone set-nsec3``. Default is NSEC, in which case no further configuration is necessary. From existing DNSSEC non-PowerDNS setups, live signing @@ -87,7 +87,7 @@ KSK, use .. code-block:: shell - pdnsutil import-zone-key ZONE FILENAME ksk + pdnsutil zone import-key ZONE FILENAME ksk replace ``ksk`` with ``zsk`` for a Zone Signing Key. diff --git a/docs/dnssec/modes-of-operation.rst b/docs/dnssec/modes-of-operation.rst index fa572f3096..178060503b 100644 --- a/docs/dnssec/modes-of-operation.rst +++ b/docs/dnssec/modes-of-operation.rst @@ -157,7 +157,7 @@ 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 -``pdnsutil rectify-zone`` is run to make sure that all DNSSEC-related +``pdnsutil zone rectify`` is run to make sure that all DNSSEC-related fields are set correctly in the backend. Signed AXFR @@ -187,7 +187,7 @@ database. Then, restart PowerDNS. .. note:: This SQLite database is different from the database used for the regular :doc:`SQLite 3 backend <../backends/generic-sqlite3>`. -After this, you can use ``pdnsutil secure-zone`` and all other pdnsutil +After this, you can use ``pdnsutil zone secure`` and all other pdnsutil commands on your BIND zones without trouble. .. _dnssec-modes-hybrid-bind: diff --git a/docs/dnssec/operational.rst b/docs/dnssec/operational.rst index 11013707f4..50b9d251b9 100644 --- a/docs/dnssec/operational.rst +++ b/docs/dnssec/operational.rst @@ -18,7 +18,7 @@ Manual As automation is not very widespread, DS publication often needs to occur manually as follows: -1. utilize ``pdnsutil show-zone`` to display DS and DNSKEY parameters, +1. utilize ``pdnsutil zone show`` to display DS and DNSKEY parameters, 2. transfer these parameters securely to your parent. Some parents accept DS format, while some accept DNSKEY (and use it to derive @@ -34,7 +34,7 @@ DS records from them. This works for both DS initialization (bootstrapping) and DS updates (rollovers). CDS/CDNSKEY record publication can be enabled using -``pdnsutil set-publish-cds`` / ``pdnsutil set-publish-cdnskey``. +``pdnsutil zone set-publish-cds`` or ``pdnsutil zone set-publish-cdnskey``. For bootstrapping, this method lacks authentication (there is no preexisting chain of trust). Some registries work around this by observing CDS/CDNSKEY @@ -64,8 +64,8 @@ enable authenticated bootstrapping as follows: .. code-block:: shell nshost=ns1.example.net - pdnsutil create-zone _signal.$nshost $nshost # create NS record too - pdnsutil set-signaling-zone _signal.$nshost + pdnsutil zone create _signal.$nshost $nshost # create NS record too + pdnsutil zone set-signaling _signal.$nshost You can do this on ``ns1.example.net`` directly, or on another instance serving the same zones. This is useful when not all instances are @@ -81,7 +81,7 @@ Note: A nameserver can't bootstrap its own parent. (The above example won't work to bootstrap ``example.net``; see step 1.) If no other zones are served under that hostname, you can skip creating its signaling zone. -``pdnsutil set-signaling-zone _signal.$nshost`` is equivalent to securing +``pdnsutil zone set-signaling _signal.$nshost`` is equivalent to securing the zone, enabling NSEC3 narrow mode, and setting the ``SIGNALING-ZONE`` metadata, which will make the zone behave as an :rfc:`9615` signaling zone. @@ -90,7 +90,7 @@ Going insecure .. code-block:: shell - pdnsutil disable-dnssec ZONE + pdnsutil zone dnssec-disable ZONE .. warning:: Going insecure with a zone that has a DS record in the @@ -107,13 +107,13 @@ NSEC3 instead, issue: .. code-block:: shell - pdnsutil set-nsec3 ZONE [PARAMETERS] ['narrow'] + pdnsutil zone set-nsec3 ZONE [PARAMETERS] ['narrow'] e.g. .. code-block:: shell - pdnsutil set-nsec3 example.net '1 0 0 -' + pdnsutil zone set-nsec3 example.net '1 0 0 -' The quoted part is the content of the NSEC3PARAM records, as defined in :rfc:`RFC 5155 <5155#section-4>`, in order: @@ -133,7 +133,7 @@ To convert a zone from NSEC3 to NSEC operations, run: .. code-block:: shell - pdnsutil unset-nsec3 ZONE + pdnsutil zone unset-nsec3 ZONE .. warning:: Don't change from NSEC to NSEC3 (or the other way around) diff --git a/docs/dnssec/pdnsutil.rst b/docs/dnssec/pdnsutil.rst index 9c35f65eaa..38edb0bf90 100644 --- a/docs/dnssec/pdnsutil.rst +++ b/docs/dnssec/pdnsutil.rst @@ -14,7 +14,7 @@ For a list of available commands, see the :doc:`manpage <../manpages/pdnsutil.1> DNSSEC Defaults --------------- -Since version 4.0, when securing a zone using ``pdnsutil secure-zone``, +Since version 4.0, when securing a zone using ``pdnsutil zone secure``, a single ECDSA (algorithm 13, ECDSAP256SHA256) key is generated that is used as CSK. Before 4.0, 3 RSA (algorithm 8) keys were generated, one as the KSK and two ZSKs. As all keys are online in the database, it made no diff --git a/docs/dnssec/pkcs11.rst b/docs/dnssec/pkcs11.rst index 7f5164bd0a..4ea6175c0a 100644 --- a/docs/dnssec/pkcs11.rst +++ b/docs/dnssec/pkcs11.rst @@ -38,7 +38,7 @@ These instructions have been tested on Debian 10 (Buster). - Verify that everything worked, you should see valid data there:: - pdnsutil show-zone example.com + pdnsutil zone show example.com SoftHSM2 with forwarding ------------------------ @@ -92,7 +92,7 @@ Then assign the HSM token to your zone with:: pdnsutil hsm assign example.com ecdsa256 ksk p11-kit-client 'ecdsa#1' 1234 'my key' -And then verify with ``show-zone`` that the zone now has a valid key. +And then verify with ``zone show`` that the zone now has a valid key. You can do this over SSH as well (note that the example connects from token server to DNS server):: @@ -171,7 +171,7 @@ Smart Card token on Ubuntu 14.04. - Verify that everything worked, you should see valid data there. :: - pdnsutil show-zone zone + pdnsutil zone show zone - Note that the physical token is pretty slow, so you have to use it as hidden primary. It has been observed to produce about 1.5 signatures/second. diff --git a/docs/dnsupdate.rst b/docs/dnsupdate.rst index e676a86f28..8d1eae4a0b 100644 --- a/docs/dnsupdate.rst +++ b/docs/dnsupdate.rst @@ -111,7 +111,7 @@ options (See :ref:`above `). This will allow 198.51.100.0/8 and 203.0.113.2/32 to send DNS update messages for the example.org domain:: - pdnsutil set-meta example.org ALLOW-DNSUPDATE-FROM 198.51.100.0/8 203.0.113.2/32 + pdnsutil metadata set example.org ALLOW-DNSUPDATE-FROM 198.51.100.0/8 203.0.113.2/32 .. _metadata-tsig-allow-dnsupdate: @@ -123,20 +123,20 @@ update. If you have GSS-TSIG enabled, you can use Kerberos principals here. Here is an example using :program:`pdnsutil` to create a key named `test`:: - $ pdnsutil generate-tsig-key test hmac-sha512 + $ pdnsutil tsigkey generate test hmac-sha512 Create new TSIG key test hmac-sha512 [base64-encoded key] - $ pdnsutil list-tsig-keys | grep test + $ pdnsutil tsigkey list | grep test test. hmac-sha512. [base64-encoded key] This adds the key with the name `test` to the zone's metadata. Note, the -keys need to be added separately with `add-meta`, not as a comma or +keys need to be added separately with `metadata add`, not as a comma or space-separated list:: - $ pdnsutil add-meta example.org TSIG-ALLOW-DNSUPDATE test + $ pdnsutil metadata add example.org TSIG-ALLOW-DNSUPDATE test Set 'example.org' meta TSIG-ALLOW-DNSUPDATE = test - $ pdnsutil get-meta example.org TSIG-ALLOW-DNSUPDATE + $ pdnsutil metadata get example.org TSIG-ALLOW-DNSUPDATE TSIG-ALLOW-DNSUPDATE = test This is an example of using the new `test` TSIG key with the :program:`nsupdate` @@ -172,7 +172,7 @@ FORWARD-DNSUPDATE See :ref:`Configuration options ` for what it does, but per domain:: - pdnsutil set-meta example.org FORWARD-DNSUPDATE 'yes' + pdnsutil metadata set example.org FORWARD-DNSUPDATE 'yes' The existence of the entry (even with an empty value) enables the forwarding. This domain-specific setting is only useful when the configuration @@ -189,7 +189,7 @@ Send a notification to all secondary servers after every update. This will speed up the propagation of changes and is very useful for acme verification:: - pdnsutil set-meta example.org NOTIFY-DNSUPDATE 1 + pdnsutil metadata set example.org NOTIFY-DNSUPDATE 1 .. _metadata-soa-edit-dnsupdate: @@ -220,7 +220,7 @@ logic to change the SOA is not executed. An example:: - pdnsutil set-meta example.org SOA-EDIT-DNSUPDATE INCREASE + pdnsutil metadata set example.org SOA-EDIT-DNSUPDATE INCREASE This will make the SOA Serial increase by one, for every successful update. @@ -363,8 +363,8 @@ domainmetadata table. :: - pdnsutil set-meta example.org ALLOW-DNSUPDATE-FROM 127.0.0.1 - pdnsutil set-meta 1.168.192.in-addr.arpa ALLOW-DNSUPDATE-FROM 127.0.0.1 + pdnsutil metadata set example.org ALLOW-DNSUPDATE-FROM 127.0.0.1 + pdnsutil metadata set 1.168.192.in-addr.arpa ALLOW-DNSUPDATE-FROM 127.0.0.1 This gives the ip '127.0.0.1' access to send update messages. Make sure you use the ip address of the machine that runs **dhcpd**. @@ -374,9 +374,9 @@ via the domainmetadata table: :: - pdnsutil import-tsig-key dhcpdupdate hmac-md5 FYhvwsW1ZtFZqWzsMpqhbg== - pdnsutil set-meta example.org TSIG-ALLOW-DNSUPDATE dhcpdupdate - pdnsutil set-meta 1.168.192.in-addr.arpa TSIG-ALLOW-DNSUPDATE dhcpdupdate + pdnsutil tsigkey import dhcpdupdate hmac-md5 FYhvwsW1ZtFZqWzsMpqhbg== + pdnsutil metadata set example.org TSIG-ALLOW-DNSUPDATE dhcpdupdate + pdnsutil metadata set 1.168.192.in-addr.arpa TSIG-ALLOW-DNSUPDATE dhcpdupdate This will: diff --git a/docs/domainmetadata.rst b/docs/domainmetadata.rst index b52858dc58..82ef64fd4e 100644 --- a/docs/domainmetadata.rst +++ b/docs/domainmetadata.rst @@ -15,7 +15,7 @@ For the implementation in non-sql backends, please review your backend's documentation. Apart from raw SQL statements, setting domain metadata can be done with -``pdnsutil set-meta`` and retrieving metadata is done with ``pdnsutil get-meta``. +``pdnsutil metadata set`` and retrieving metadata is done with ``pdnsutil metadata get``. The following options can only be read (not written to) via the HTTP API metadata endpoint. @@ -46,7 +46,7 @@ Example: .. code-block:: shell - pdnsutil set-meta powerdns.org ALLOW-AXFR-FROM AUTO-NS 2001:db8::/48 + pdnsutil metadata set powerdns.org ALLOW-AXFR-FROM AUTO-NS 2001:db8::/48 Each ACL has its own row in the database: @@ -78,8 +78,8 @@ number. e.g.: .. code-block:: shell - pdnsutil set-meta powerdns.org ALSO-NOTIFY 192.0.2.1:5300 - pdnsutil set-meta powerdns.org ALLOW-AXFR-FROM 2001:db8:53::1 + pdnsutil metadata set powerdns.org ALSO-NOTIFY 192.0.2.1:5300 + pdnsutil metadata set powerdns.org ALLOW-AXFR-FROM 2001:db8:53::1 API-RECTIFY @@ -150,14 +150,14 @@ NSEC3NARROW ----------- Set to "1" to tell PowerDNS this zone operates in NSEC3 'narrow' mode. -See ``set-nsec3`` for :doc:`pdnsutil `. +See ``zone set-nsec3`` for :doc:`pdnsutil `. NSEC3PARAM ---------- NSEC3 parameters of a DNSSEC zone. Will be used to synthesize the NSEC3PARAM record. If present, NSEC3 is used, if not present, zones -default to NSEC. See ``set-nsec3`` in :doc:`pdnsutil `. +default to NSEC. See ``zone set-nsec3`` in :doc:`pdnsutil `. Example content: "1 0 0 -". .. _metadata-presigned: @@ -168,10 +168,10 @@ PRESIGNED This zone carries DNSSEC RRSIGs (signatures), and is presigned. PowerDNS sets this flag automatically upon incoming zone transfers (AXFR) if it detects DNSSEC records in the zone. However, if you import a presigned -zone using ``zone2sql`` or ``pdnsutil load-zone`` you must explicitly +zone using ``zone2sql`` or ``pdnsutil zone load`` you must explicitly set the zone to be ``PRESIGNED``. Note that PowerDNS will not be able to correctly serve the zone if the imported data is bogus or incomplete. -Also see ``set-presigned`` in :doc:`pdnsutil `. +Also see ``zone set-presigned`` in :doc:`pdnsutil `. If a zone is presigned, the content of the metadata must be "1" (without the quotes). Any other value will not signal presignedness. @@ -191,8 +191,8 @@ a comma- separated list of `signature algorithm numbers `__. This metadata can also be set using the -:doc:`pdnsutil ` commands ``set-publish-cdnskey`` -and ``set-publish-cds``. For an example for an :rfc:`7344` key rollover, +:doc:`pdnsutil ` commands ``zone set-publish-cdnskey`` +and ``zone set-publish-cds``. For an example for an :rfc:`7344` key rollover, see the :doc:`guides/kskrollcdnskey`. Global defaults for these values can be set via :ref:`setting-default-publish-cdnskey` and :ref:`setting-default-publish-cds`. @@ -260,7 +260,7 @@ If :ref:`GSS-TSIG ` is enabled, you can put Kerberos principals h Extra metadata -------------- -Through the API and on the ``pdnsutil set-meta`` commandline, metadata +Through the API and on the ``pdnsutil metadata set`` commandline, metadata unused by PowerDNS can be added. It is mandatory to prefix this extra metadata with "X-" and the name of the external application; the API will only allow this metadata if it starts with "X-". diff --git a/docs/guides/algoroll.rst b/docs/guides/algoroll.rst index 21badf4e92..d8b72d70c9 100644 --- a/docs/guides/algoroll.rst +++ b/docs/guides/algoroll.rst @@ -16,7 +16,7 @@ Please check that these bigger packets can make it out of your network without t .. warning:: For every mutation to your zone (so, every step except updating DS in the parent), make sure that your serial is bumped, so your secondaries pick up the changes too. - If you are using AXFR replication, this usually is as simple as ``pdnsutil increase-serial example.com`` + If you are using AXFR replication, this usually is as simple as ``pdnsutil zone increase-serial example.com`` Phase: initial -------------- @@ -31,11 +31,11 @@ To create signatures with the new algorithm, without publishing keys, run someth .. code-block:: shell - pdnsutil add-zone-key example.com KSK active unpublished ecdsa384 - pdnsutil add-zone-key example.com ZSK active unpublished ecdsa384 + pdnsutil zone add-key example.com KSK active unpublished ecdsa384 + pdnsutil zone add-key example.com ZSK active unpublished ecdsa384 -Note the key IDs that add-zone-key reports. -You can also retrieve these later with ``pdnsutil show-zone example.com``. +Note the key IDs that ``zone add-key`` reports. +You can also retrieve these later with ``pdnsutil zone show example.com``. After this, PowerDNS will sign all records in the zone with both the old and new ZSKs, and the DNSKEY set will be signed by both KSKs. @@ -61,10 +61,10 @@ After waiting for all records in our zone to expire from caches, we can publish .. code-block:: shell - pdnsutil publish-zone-key example.com 3 - pdnsutil publish-zone-key example.com 4 + pdnsutil zone publish-key example.com 3 + pdnsutil zone publish-key example.com 4 -Replace ``3`` and ``4`` with the key IDs gathered in the previous step, or find them in ``pdnsutil show-zone example.com``. +Replace ``3`` and ``4`` with the key IDs gathered in the previous step, or find them in ``pdnsutil zone show example.com``. PowerDNS will now publish the new DNSKEYs that have already been used for signing for a while. The old DNSKEYs remain published, and active for signing, for now. @@ -81,7 +81,7 @@ Our zone is currently fully signed with two algorithms, and keys for both algori This means that a DS for either the old or new algorithm is sufficient for validation. We can now switch the DS - there is no need to have DSes for both algorithms in the parent zone. -Using ``pdnsutil show-zone example.com`` or ``pdnsutil export-zone-ds example.com``, extract the new DNSKEYs or new DSes, depending on what the parent zone operator takes as input. +Using ``pdnsutil zone show example.com`` or ``pdnsutil zone export-ds example.com``, extract the new DNSKEYs or new DSes, depending on what the parent zone operator takes as input. Note that these commands print DNSKEYs and/or DSes for both the old and the new algorithm. Check the DS TTL at the parent, for example: ``dig DS example.com @c.gtld-servers.net`` for a delegation from ``.com``. @@ -102,8 +102,8 @@ It is time to remove the old DNSKEYs, while keeping their signature: .. code-block:: shell - pdnsutil unpublish-zone-key example.com 1 - pdnsutil unpublish-zone-key example.com 2 + pdnsutil zone unpublish-key example.com 1 + pdnsutil zone unpublish-key example.com 2 Replace ``1`` and ``2`` with the IDs of the old keys. @@ -120,14 +120,14 @@ This means we can now safely stop signing with the old keys: .. code-block:: shell - pdnsutil deactivate-zone-key example.com 1 - pdnsutil deactivate-zone-key example.com 2 + pdnsutil zone deactivate-key example.com 1 + pdnsutil zone deactivate-key example.com 2 -Alternatively, you can use ``remove-zone-key`` to remove all traces of the old keys. +Alternatively, you can use ``zone remove-key`` to remove all traces of the old keys. Conclusion ---------- In another hours-to-a-few-days, the old signatures will expire from caches. -Your algorithm roll is complete. \ No newline at end of file +Your algorithm roll is complete. diff --git a/docs/guides/basic-database.rst b/docs/guides/basic-database.rst index 9bf15919b6..a99f347d15 100644 --- a/docs/guides/basic-database.rst +++ b/docs/guides/basic-database.rst @@ -64,13 +64,13 @@ Note the ``REFUSED`` status - this is the code most name servers use to indicate Now, let's add a zone and some records:: - $ sudo -u pdns pdnsutil create-zone example.com ns1.example.com + $ sudo -u pdns pdnsutil zone create example.com ns1.example.com Creating empty zone 'example.com' Also adding one NS record - $ sudo -u pdns pdnsutil add-record example.com example.com MX '25 mail.example.com' + $ sudo -u pdns pdnsutil rrset add example.com example.com MX '25 mail.example.com' New rrset: example.com. 3005 IN MX 25 mail.example.com - $ sudo -u pdns pdnsutil add-record example.com www.example.com A 192.0.2.1 + $ sudo -u pdns pdnsutil rrset add example.com www.example.com A 192.0.2.1 New rrset: www.example.com. 3005 IN A 192.0.2.1 @@ -95,7 +95,7 @@ If you see old, or no, data right after changing records, wait for :ref:`setting :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. +Now, run ``pdnsutil zone edit example.com`` and try to add a few more records, and query them with dig to make sure they work. You now have a working database driven nameserver! diff --git a/docs/guides/kskroll.rst b/docs/guides/kskroll.rst index a73892d364..192b6ea027 100644 --- a/docs/guides/kskroll.rst +++ b/docs/guides/kskroll.rst @@ -11,7 +11,7 @@ After every change, use your favourite DNSSEC checker (`DNSViz ` checks if the autohints in SVCB and derived records can be found in the zone when using ``pdnsutil check-zone``. +:doc:`pdnsutil <../manpages/pdnsutil.1>` checks if the autohints in SVCB and derived records can be found in the zone when using ``pdnsutil zone check``. It will emit a warning when there are no hints to be found:: [warning] HTTPS record for no-ipv6.example.org has automatic IPv6 hints, but no AAAA-record for the target at no-ipv6.example.org exists. diff --git a/docs/guides/zskroll.rst b/docs/guides/zskroll.rst index 22b73e6ba3..f5cb72dcf8 100644 --- a/docs/guides/zskroll.rst +++ b/docs/guides/zskroll.rst @@ -15,7 +15,7 @@ After every change, use your favourite DNSSEC checker (`DNSViz [arguments...]``, where ```` is a noun and ```` is a verb; a few commands which do not apply to any particular object +kind use only the verb. -DNSSEC-RELATED COMMANDS ------------------------ - -Several commands manipulate the DNSSEC keys and options for zones. Some -of these commands require an *ALGORITHM* to be set. The following -algorithms are supported: - -- rsasha1 -- rsasha1-nsec3-sha1 -- rsasha256 -- rsasha512 -- ecdsa256 -- ecdsa384 -- ed25519 -- ed448 - -.. note:: - ed25519 and ed448 algorithms will only be available if adequate cryptographic - libraries have been available while compiling PowerDNS on your particular - system. - -In addition to the algorithm, some commands below may ask for a key size in -bits. The key size may be omitted for the ECC algorithms, which support only -one valid size per algorithm; for ECDSA256 and ED25519, it is 256; -for ECDSA384, it is 384; and for ED448, it is... 456. +AUTOPRIMARY COMMANDS +-------------------- -activate-zone-key *ZONE* *KEY_ID* +autoprimary add *IP* *NAMESERVER* [*ACCOUNT*] - Activate a key with id *KEY_ID* within a zone called *ZONE*. - -add-zone-key *ZONE* [**KSK**,\ **ZSK**] [**active**,\ **inactive**] [**published**,\ **unpublished**] *ALGORITHM* [*KEYBITS*] - - Create a new key for zone *ZONE*, and make it a KSK (default) or a ZSK, with - the specified *ALGORITHM* and *KEYBITS*. If *KEYBITS* is omitted, the value - of :ref:`setting-default-ksk-size` or :ref:`setting-default-zsk-size` are - used. - - The key is inactive by default, set it to **active** to immediately use it - to sign *ZONE*. The key is published in the zone by default, set it to - **unpublished** to keep it from being returned in a DNSKEY query, which is - useful for algorithm rollovers. - - Prints the id of the added key. - -create-bind-db *FILENAME* - - Create DNSSEC database (sqlite3) at *FILENAME* for the BIND backend. - Remember to set ``bind-dnssec-db=*FILE*`` in your ``pdns.conf``. - -deactivate-zone-key *ZONE* *KEY_ID* - - Deactivate a key with id KEY_ID within a zone called *ZONE*. - -disable-dnssec *ZONE* - - Deactivate all keys and unset PRESIGNED in *ZONE*. + Add a autoprimary entry into the backend. This enables receiving zone + updates from other servers. -export-zone-dnskey *ZONE* *KEY_ID* +autoprimary list - Export DNSKEY and DS of key with key id *KEY_ID* within zone *ZONE* to - standard output. + List all autoprimaries. -export-zone-ds *ZONE* +autoprimary remove *IP* *NAMESERVER* - Export all KSK DS records for *ZONE* to standard output. + Remove an autoprimary from backend. Not supported by BIND backend. -export-zone-key *ZONE* *KEY_ID* +CATALOG ZONE COMMANDS +--------------------- - Export full (private) key with key id *KEY_ID* within zone *ZONE* to - standard output. The format used is compatible with BIND and NSD/LDNS. +catalog list-members *CATALOG* -export-zone-key-pem *ZONE* *KEY_ID* + List all members of catalog zone *CATALOG*" - Export full (private) key with key id *KEY_ID* within zone *ZONE* to - standard output in the PEM file format. The format is compatible with - many non-DNS software products. +catalog set *ZONE* [*CATALOG*] -generate-zone-key {**KSK**,\ **ZSK**} [*ALGORITHM*] [*KEYBITS*] + Change the catalog of *ZONE* to *CATALOG*. If *CATALOG* is omitted, + removes *ZONE* from the catalog it is in. - Generate a ZSK or KSK with specified algorithm and bits and print it - on standard output. If *ALGORITHM* is not set, ECDSA256 is used. - If *KEYBITS* is not set, an appropriate keysize is selected - for *ALGORITHM*: for RSA keys, 2048 bits for KSK and 1024 bits for ZSK; - for ECC keys, the algorithm-required size as mentioned above. +ZONE METADATA COMMANDS +---------------------- -import-zone-key *ZONE* *FILE* [**KSK**,\ **ZSK**] [**active**,\ **inactive**] [**published**,\ **unpublished**] +metadata add *ZONE* *KIND* *VALUE* [*VALUE*]... - Import from *FILE* a full (private) key for the zone *ZONE*. The - format used is compatible with BIND and NSD/LDNS. **KSK** or **ZSK** - specifies the flags this key should have on import. Defaults to KSK, - active and published. Prints the id of the added key. - -import-zone-key-pem *ZONE* *FILE* *ALGORITHM* {**KSK**,\ **ZSK**} - - Import from PEM *FILE* a full (private) key for the zone *ZONE* with a - specified *ALGORITHM*. The format used is compatible with many non-DNS - software products. **KSK** or **ZSK** specifies the flags this key should - have on import. Prints the id of the added key. + Append *VALUE* to the existing *KIND* metadata for *ZONE*. + Will return an error if *KIND* does not support multiple values, use + ``metadata set`` for these values. -publish-zone-key *ZONE* *KEY_ID* +metadata get *ZONE* [*KIND*]... - Publish the key with id *KEY_ID* within zone *ZONE*. + Get zone metadata. If no *KIND* given, lists all known. -remove-zone-key *ZONE* *KEY_ID* +metadata set *ZONE* *KIND* [*VALUE*]... - Remove a key with id *KEY_ID* from zone *ZONE*. + Set zone metadata *KIND* for *ZONE* to *VALUE*, replacing all existing + values of *KIND*. An omitted value clears it. -set-nsec3 *ZONE* ['*HASH-ALGORITHM* *FLAGS* *ITERATIONS* *SALT*'] [**narrow**] +NETWORK COMMANDS +---------------- - Sets NSEC3 parameters for this zone. The quoted parameters are 4 - values that are used for the NSEC3PARAM record and decide how - 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:`RFC 5155<5155#section-10.3>`. +network list - 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 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 zone transfers are denied. - - If only the zone is provided as argument, the 4-parameter quoted string - defaults to ``'1 0 0 -'``, as recommended by :rfc:`9276`. - - A sample commandline would be: - - ``pdnsutil set-nsec3 powerdnssec.org '1 1 1 ab' narrow`` - - **WARNING**: If running in RSASHA1 mode (algorithm 5 or 7), switching - from NSEC to NSEC3 will require a DS update in the parent zone. + List all defined networks with their chosen views. -unpublish-zone-key *ZONE* *KEY_ID* +network set *NET* [*VIEW*] - Unpublish the key with id *KEY_ID* within zone *ZONE*. + Set the *VIEW* for a the *NET* network, or delete if no *VIEW* argument. -unset-nsec3 *ZONE* +ZONE RECORD COMMANDS +-------------------- - Converts *ZONE* to NSEC operations. **WARNING**: If running in - RSASHA1 mode (algorithm 5 or 7), switching from NSEC to NSEC3 will - require a DS update at the parent zone! +In these commands, the ``rrset`` object name may also be written as ``record``. -set-publish-cds *ZONE* [*DIGESTALGOS*] +rrset add *ZONE* *NAME* *TYPE* [*TTL*] *CONTENT* - Set *ZONE* to respond to queries for its CDS records. the optional - argument *DIGESTALGOS* should be a comma-separated list of DS - algorithms to use. By default, this is 2 (SHA-256). 0 will publish a - CDS with a DNSSEC delete algorithm. + Add one or more records of *NAME* and *TYPE* to *ZONE* with *CONTENT* + and optional *TTL*. If *TTL* is not set, the configured *default-ttl* will be used. + *NAME* must be absolute. -set-publish-cdnskey *ZONE* [**delete**] +rrset delete *ZONE* *NAME* *TYPE* - Set *ZONE* to publish CDNSKEY records. Add 'delete' to publish a CDNSKEY - with a DNSSEC delete algorithm. + Delete named RRSET from zone. + *NAME* must be absolute. -unset-publish-cds *ZONE* +rrset hash *ZONE* *RNAME* - Set *ZONE* to stop responding to queries for its CDS records. + This convenience command hashes the name *RNAME* according to the + NSEC3 settings of *ZONE*. Refuses to hash for zones with no NSEC3 + settings. -unset-publish-cdnskey *ZONE* +rrset replace *ZONE* *NAME* *TYPE* [*TTL*] *CONTENT* [*CONTENT*...] - Set *ZONE* to stop publishing CDNSKEY records. + Replace existing *NAME* in zone *ZONE* with a new set. TSIG RELATED COMMANDS --------------------- These commands manipulate TSIG key information in the database. Some -commands require an *ALGORITHM*, the following are available: +commands require an *ALGORITHM*, which can be any of the following: - hmac-md5 - hmac-sha1 @@ -212,258 +128,351 @@ commands require an *ALGORITHM*, the following are available: - hmac-sha384 - hmac-sha512 -activate-tsig-key *ZONE* *NAME* {**primary**,\ **secondary**,\ **producer**,\ **consumer**} +tsigkey activate *ZONE* *NAME* {**primary**,\ **secondary**,\ **producer**,\ **consumer**} Enable TSIG authenticated AXFR using the key *NAME* for zone *ZONE*. This sets the ``TSIG-ALLOW-AXFR`` (primary/producer) or ``AXFR-MASTER-TSIG`` (secondary/consumer) zone metadata. -deactivate-tsig-key *ZONE* *NAME* {**primary**,\ **secondary**,\ **producer**,\ **consumer**} +tsigkey deactivate *ZONE* *NAME* {**primary**,\ **secondary**,\ **producer**,\ **consumer**} Disable TSIG authenticated AXFR using the key *NAME* for zone *ZONE*. -delete-tsig-key *NAME* +tsigkey delete *NAME* Delete the TSIG key *NAME*. Warning: this does not deactivate said key. -generate-tsig-key *NAME* *ALGORITHM* +tsigkey generate *NAME* *ALGORITHM* Generate new TSIG key with name *NAME* and the specified algorithm. -import-tsig-key *NAME* *ALGORITHM* *KEY* +tsigkey import *NAME* *ALGORITHM* *KEY* Import *KEY* of the specified algorithm as *NAME*. -list-tsig-keys +tsigkey list Show a list of all configured TSIG keys. +VIEWS COMMANDS +-------------- + +views add-zone *VIEW* *ZONE..VARIANT* + + Add the given *ZONE* *VARIANT* to a *VIEW*. + +views del-zone *VIEW* *ZONE..VARIANT* + + Remove a *ZONE* *VARIANT* from a *VIEW*. + +views list *VIEW* + + List all zones within *VIEW*. + +views list-all + + List all view names. + ZONE MANIPULATION COMMANDS -------------------------- -add-record *ZONE* *NAME* *TYPE* [*TTL*] *CONTENT* +zone check *ZONE* - Add one or more records of *NAME* and *TYPE* to *ZONE* with *CONTENT* - and optional *TTL*. If *TTL* is not set, the configured *default-ttl* will be used. - *NAME* must be absolute. + Check zone *ZONE* for correctness. -add-autoprimary *IP* *NAMESERVER* [*ACCOUNT*] +zone check-all [exit-on-error] - Add a autoprimary entry into the backend. This enables receiving zone - updates from other servers. + Check all zones for correctness, aborting upon finding the first error + in any zone if "exit-on-error" is specified. -remove-autoprimary *IP* *NAMESERVER* +zone clear *ZONE* - Remove an autoprimary from backend. Not supported by BIND backend. + Clear the records in zone *ZONE*, but leave actual zone and + settings unchanged -list-autoprimaries +zone create *ZONE* - List all autoprimaries. + Create an empty zone named *ZONE*. -create-zone *ZONE* +zone delete *ZONE* - Create an empty zone named *ZONE*. + Delete the zone named *ZONE*. -create-secondary-zone *ZONE* *PRIMARY* [*PRIMARY*]... +zone edit *ZONE* - Create a new secondary zone *ZONE* with primaries *PRIMARY*. All *PRIMARY*\ s - need to to be space-separated IP addresses with an optional port. + Opens *ZONE* in zonefile format (regardless of backend it was loaded + from) in the editor set in the environment variable **EDITOR**. if + **EDITOR** is empty, *pdnsutil* falls back to using *editor*. -change-secondary-zone-primary *ZONE* *PRIMARY* [*PRIMARY*]... +zone increase-serial *ZONE* - Change the primaries for secondary zone *ZONE* to new primaries *PRIMARY*. All - *PRIMARY*\ s need to to be space-separated IP addresses with an optional port. + Increases the SOA-serial by 1. Uses SOA-EDIT. -check-all-zones +zone list *ZONE* - Check all zones for correctness. + Show all records for *ZONE*. -check-zone *ZONE* +zone list-all *KIND* - Check zone *ZONE* for correctness. + List all active zone names of the given *KIND* (primary, secondary, + native, producer, consumer), or all if none given. Passing --verbose or + -v will also include disabled or empty zones. -clear-zone *ZONE* +zone load *ZONE* *FILE* - Clear the records in zone *ZONE*, but leave actual zone and - settings unchanged + Load records for *ZONE* from *FILE*. If *ZONE* already exists, all + records are overwritten, this operation is atomic. If *ZONE* doesn't + exist, it is created. -delete-rrset *ZONE* *NAME* *TYPE* +zone set-account *ZONE* *ACCOUNT* - Delete named RRSET from zone. - *NAME* must be absolute. + Change the account (owner) of *ZONE* to *ACCOUNT*. -delete-zone *ZONE* +zone set-kind *ZONE* *KIND* - Delete the zone named *ZONE*. + Change the kind of *ZONE* to *KIND* (primary, secondary, native, producer, + consumer). -edit-zone *ZONE* +zone set-option *ZONE* [*producer* | *consumer*] [*coo* | *unique* | *group*] *VALUE* [*VALUE* ...] - Opens *ZONE* in zonefile format (regardless of backend it was loaded - from) in the editor set in the environment variable **EDITOR**. if - **EDITOR** is empty, *pdnsutil* falls back to using *editor*. + Set or remove an option for *ZONE*. Providing an empty value removes + an option. -hash-password [*WORK_FACTOR*] +zone set-options-json *ZONE* *JSONFILE* - This convenience command reads a password (not echoed) from standard - input and returns a hashed and salted version, for use as a webserver - password or api key. - An optional scrypt work factor can be specified, in powers of two, - otherwise it defaults to 1024. + Change the options of *ZONE* to the contents of *JSONFILE*. -hash-zone-record *ZONE* *RNAME* +zone zonemd-verify-file *ZONE* *FILE* - This convenience command hashes the name *RNAME* according to the - NSEC3 settings of *ZONE*. Refuses to hash for zones with no NSEC3 - settings. + Validate ZONEMD for *ZONE* read from *FILE*. -increase-serial *ZONE* +SECONDARY ZONE COMMANDS +----------------------- - Increases the SOA-serial by 1. Uses SOA-EDIT. +zone change-primary *ZONE* *PRIMARY* [*PRIMARY*]... -list-keys [*ZONE*] + Change the primaries for secondary zone *ZONE* to new primaries *PRIMARY*. All + *PRIMARY*\ s need to to be space-separated IP addresses with an optional port. - List DNSSEC information for all keys or for *ZONE* only. Passing - --verbose or -v will also include the keys for disabled or empty zones. +zone create-secondary *ZONE* *PRIMARY* [*PRIMARY*]... -list-all-zones *KIND* + Create a new secondary zone *ZONE* with primaries *PRIMARY*. All *PRIMARY*\ s + need to to be space-separated IP addresses with an optional port. - List all active zone names of the given *KIND* (primary, secondary, - native, producer, consumer), or all if none given. Passing --verbose or - -v will also include disabled or empty zones. +DNSSEC-RELATED COMMANDS +----------------------- -list-member-zones *CATALOG* +Several commands manipulate the DNSSEC keys and options for zones. Some +of these commands require an *ALGORITHM* to be set. The following +algorithms are supported: - List all members of catalog zone *CATALOG*" +- rsasha1 +- rsasha1-nsec3-sha1 +- rsasha256 +- rsasha512 +- ecdsa256 +- ecdsa384 +- ed25519 +- ed448 -list-zone *ZONE* +.. note:: + ed25519 and ed448 algorithms will only be available if adequate cryptographic + libraries have been available while compiling PowerDNS on your particular + system. - Show all records for *ZONE*. +In addition to the algorithm, some commands below may ask for a key size in +bits. The key size may be omitted for the ECC algorithms, which support only +one valid size per algorithm; for ECDSA256 and ED25519, it is 256; +for ECDSA384, it is 384; and for ED448, it is... 456. -load-zone *ZONE* *FILE* +zone dnssec-disable *ZONE* - Load records for *ZONE* from *FILE*. If *ZONE* already exists, all - records are overwritten, this operation is atomic. If *ZONE* doesn't - exist, it is created. + Deactivate all keys and unset PRESIGNED in *ZONE*. + +zone export-dnskey *ZONE* *KEY_ID* + + Export DNSKEY and DS of key with key id *KEY_ID* within zone *ZONE* to + standard output. -rectify-zone *ZONE* +zone export-ds *ZONE* + + Export all KSK DS records for *ZONE* to standard output. + +zone list-keys [*ZONE*] + + List DNSSEC information for all keys or for *ZONE* only. Passing + --verbose or -v will also include the keys for disabled or empty zones. + +zone rectify *ZONE* Calculates the 'ordername' and 'auth' fields for a zone called *ZONE* so they comply with DNSSEC settings. Can be used to fix up migrated data. -rectify-all-zones +zone rectify-all Calculates the 'ordername' and 'auth' fields for all zones so they comply with DNSSEC settings. Can be used to fix up migrated data. -replace-rrset *ZONE* *NAME* *TYPE* [*TTL*] *CONTENT* [*CONTENT*...] - - Replace existing *NAME* in zone *ZONE* with a new set. - -secure-zone *ZONE* +zone secure *ZONE* Configures a zone called *ZONE* with reasonable DNSSEC settings. You - should manually run 'pdnsutil rectify-zone' afterwards. + should manually run 'pdnsutil zone rectify' afterwards. -secure-all-zones [**increase-serial**] +zone secure-all [**increase-serial**] Configures all zones that are not currently signed with reasonable DNSSEC settings. Setting **increase-serial** will increase the serial of those zones too. You should manually run 'pdnsutil - rectify-all-zones' afterwards. + zone rectify-all' afterwards. -set-kind *ZONE* *KIND* +zone set-nsec3 *ZONE* ['*HASH-ALGORITHM* *FLAGS* *ITERATIONS* *SALT*'] [**narrow**] - Change the kind of *ZONE* to *KIND* (primary, secondary, native, producer, - consumer). + Sets NSEC3 parameters for this zone. The quoted parameters are 4 + values that are used for the NSEC3PARAM record and decide how + 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:`RFC 5155<5155#section-10.3>`. -set-options-json *ZONE* *JSONFILE* + 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 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 zone transfers are denied. + + If only the zone is provided as argument, the 4-parameter quoted string + defaults to ``'1 0 0 -'``, as recommended by :rfc:`9276`. + + A sample commandline would be: - Change the options of *ZONE* to the contents of *JSONFILE*. + ``pdnsutil zone set-nsec3 powerdnssec.org '1 1 1 ab' narrow`` -set-option *ZONE* [*producer* | *consumer*] [*coo* | *unique* | *group*] *VALUE* [*VALUE* ...] + **WARNING**: If running in RSASHA1 mode (algorithm 5 or 7), switching + from NSEC to NSEC3 will require a DS update in the parent zone. - Set or remove an option for *ZONE*. Providing an empty value removes - an option. +zone set-presigned *ZONE* -set-catalog *ZONE* [*CATALOG*] + Switches *ZONE* to presigned operation, utilizing in-zone RRSIGs. - Change the catalog of *ZONE* to *CATALOG*. If *CATALOG* is omitted, - removes *ZONE* from the catalog it is in. +zone set-publish-cdnskey *ZONE* [**delete**] -set-account *ZONE* *ACCOUNT* + Set *ZONE* to publish CDNSKEY records. Add 'delete' to publish a CDNSKEY + with a DNSSEC delete algorithm. - Change the account (owner) of *ZONE* to *ACCOUNT*. +zone set-publish-cds *ZONE* [*DIGESTALGOS*] -add-meta *ZONE* *KIND* *VALUE* [*VALUE*]... + Set *ZONE* to respond to queries for its CDS records. the optional + argument *DIGESTALGOS* should be a comma-separated list of DS + algorithms to use. By default, this is 2 (SHA-256). 0 will publish a + CDS with a DNSSEC delete algorithm. - Append *VALUE* to the existing *KIND* metadata for *ZONE*. - Will return an error if *KIND* does not support multiple values, use - **set-meta** for these values. +zone show *ZONE* -get-meta *ZONE* [*KIND*]... + Shows all DNSSEC related settings of a zone called *ZONE*. - Get zone metadata. If no *KIND* given, lists all known. +zone unset-nsec3 *ZONE* -set-meta *ZONE* *KIND* [*VALUE*]... + Converts *ZONE* to NSEC operations. **WARNING**: If running in + RSASHA1 mode (algorithm 5 or 7), switching from NSEC to NSEC3 will + require a DS update at the parent zone! - Set zone metadata *KIND* for *ZONE* to *VALUE*, replacing all existing - values of *KIND*. An omitted value clears it. +zone unset-presigned *ZONE* -set-presigned *ZONE* + Disables presigned operation for *ZONE*. - Switches *ZONE* to presigned operation, utilizing in-zone RRSIGs. +zone unset-publish-cdnskey *ZONE* -show-zone *ZONE* + Set *ZONE* to stop publishing CDNSKEY records. - Shows all DNSSEC related settings of a zone called *ZONE*. +zone unset-publish-cds *ZONE* -test-schema *ZONE* + Set *ZONE* to stop responding to queries for its CDS records. - Test database schema, this creates the zone *ZONE* +ZONE KEY COMMANDS +----------------- -unset-presigned *ZONE* +zone activate-key *ZONE* *KEY_ID* - Disables presigned operation for *ZONE*. + Activate a key with id *KEY_ID* within a zone called *ZONE*. -raw-lua-from-content *TYPE* *CONTENT* +zone add-key *ZONE* [**KSK**,\ **ZSK**] [**active**,\ **inactive**] [**published**,\ **unpublished**] *ALGORITHM* [*KEYBITS*] - Display record contents in a form suitable for dnsdist's `SpoofRawAction`. + Create a new key for zone *ZONE*, and make it a KSK (default) or a ZSK, with + the specified *ALGORITHM* and *KEYBITS*. If *KEYBITS* is omitted, the value + of :ref:`setting-default-ksk-size` or :ref:`setting-default-zsk-size` are + used. + + The key is inactive by default, set it to **active** to immediately use it + to sign *ZONE*. The key is published in the zone by default, set it to + **unpublished** to keep it from being returned in a DNSKEY query, which is + useful for algorithm rollovers. + + Prints the id of the added key. -zonemd-verify-file *ZONE* *FILE* +zone deactivate-key *ZONE* *KEY_ID* - Validate ZONEMD for *ZONE* read from *FILE*. + Deactivate a key with id KEY_ID within a zone called *ZONE*. -VIEWS COMMANDS --------------- +zone export-key *ZONE* *KEY_ID* -list-networks + Export full (private) key with key id *KEY_ID* within zone *ZONE* to + standard output. The format used is compatible with BIND and NSD/LDNS. - List all defined networks with their chosen views. +zone export-key-pem *ZONE* *KEY_ID* -set-network *NET* [*VIEW*] + Export full (private) key with key id *KEY_ID* within zone *ZONE* to + standard output in the PEM file format. The format is compatible with + many non-DNS software products. - Set the *VIEW* for a the *NET* network, or delete if no *VIEW* argument. +zone generate-key {**KSK**,\ **ZSK**} [*ALGORITHM*] [*KEYBITS*] + + Generate a ZSK or KSK with specified algorithm and bits and print it + on standard output. If *ALGORITHM* is not set, ECDSA256 is used. + If *KEYBITS* is not set, an appropriate keysize is selected + for *ALGORITHM*: for RSA keys, 2048 bits for KSK and 1024 bits for ZSK; + for ECC keys, the algorithm-required size as mentioned above. -view-add-zone *VIEW* *ZONE..VARIANT* +zone import-key *ZONE* *FILE* [**KSK**,\ **ZSK**] [**active**,\ **inactive**] [**published**,\ **unpublished**] - Add the given *ZONE* *VARIANT* to a *VIEW*. + Import from *FILE* a full (private) key for the zone *ZONE*. The + format used is compatible with BIND and NSD/LDNS. **KSK** or **ZSK** + specifies the flags this key should have on import. Defaults to KSK, + active and published. Prints the id of the added key. -view-del-zone *VIEW* *ZONE..VARIANT* +zone import-key-pem *ZONE* *FILE* *ALGORITHM* {**KSK**,\ **ZSK**} - Remove a *ZONE* *VARIANT* from a *VIEW*. + Import from PEM *FILE* a full (private) key for the zone *ZONE* with a + specified *ALGORITHM*. The format used is compatible with many non-DNS + software products. **KSK** or **ZSK** specifies the flags this key should + have on import. Prints the id of the added key. -list-view *VIEW* +zone publish-key *ZONE* *KEY_ID* - List all within *VIEW*. + Publish the key with id *KEY_ID* within zone *ZONE*. -list-views +zone remove-key *ZONE* *KEY_ID* - List all view names. + Remove a key with id *KEY_ID* from zone *ZONE*. + +zone unpublish-key *ZONE* *KEY_ID* -DEBUGGING TOOLS ---------------- + Unpublish the key with id *KEY_ID* within zone *ZONE*. + +OTHER/MISCELLANEOUS COMMANDS +---------------------------- + +b2b-migrate *OLD* *NEW* + + Migrate data from one backend to another. + Needs ``launch=OLD,NEW`` in the configuration. backend-cmd *BACKEND* *CMD* [*CMD...*] @@ -481,23 +490,41 @@ bench-db [*FILE*] *FILE* can be a file with a list, one per line, of zone names to use for this. If *FILE* is not specified, powerdns.com is used. -OTHER TOOLS ------------ +create-bind-db *FILENAME* -b2b-migrate *OLD* *NEW* + Create DNSSEC database (sqlite3) at *FILENAME* for the BIND backend. + Remember to set ``bind-dnssec-db=*FILE*`` in your ``pdns.conf``. - Migrate data from one backend to another. - Needs ``launch=OLD,NEW`` in the configuration. +hash-password [*WORK_FACTOR*] + + This convenience command reads a password (not echoed) from standard + input and returns a hashed and salted version, for use as a webserver + password or api key. + An optional scrypt work factor can be specified, in powers of two, + otherwise it defaults to 1024. + +ipdecrypt *IP_ADDRESS* PASSPHRASE_OR_KEY [**key**] + + Decrypt an IP address according to the 'ipcipher' standard. If the + passphrase is a base64 key, add the word "key" after it. ipencrypt *IP_ADDRESS* PASSPHRASE_OR_KEY [**key**] Encrypt an IP address according to the 'ipcipher' standard. If the passphrase is a base64 key, add the word "key" after it. -ipdecrypt *IP_ADDRESS* PASSPHRASE_OR_KEY [**key**] +list-algorithms [with-backend] - Decrypt an IP address according to the 'ipcipher' standard. If the - passphrase is a base64 key, add the word "key" after it. + List all DNSSEC algorithms supported, optionally also listing the + cryptographic library used if "with-backend" is specified. + +test-schema *ZONE* + + Test database schema, this creates the zone *ZONE* + +raw-lua-from-content *TYPE* *CONTENT* + + Display record contents in a form suitable for dnsdist's `SpoofRawAction`. See also -------- diff --git a/docs/migration.rst b/docs/migration.rst index dd9258eceb..5f209d1e3e 100644 --- a/docs/migration.rst +++ b/docs/migration.rst @@ -123,15 +123,15 @@ An example call to ``zone2sql`` could be: This will generate the SQL statements for the :doc:`Generic MySQL ` and pipe them into the pdns-db database in MySQL. -Using ``pdnsutil load-zone`` +Using ``pdnsutil zone load`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The :doc:`pdnsutil ` tool has a -``load-zone`` command that ingests a zone file and imports it into the +``zone load`` command that ingests a zone file and imports it into the first backend that is capable of hosting it. To import, configure the backend and run -``pdnsutil load-zone example.com /tmp/example.com.zone`` to import +``pdnsutil zone load example.com /tmp/example.com.zone`` to import the ``example.com`` domain from the ``/tmp/example.com.zone`` file. The zone is imported atomically (i.e. it is fully imported, or not) and any existing records for that zone are overwritten. This include the SOA record too. @@ -175,7 +175,7 @@ Moving from source to target sure you properly clear **ALL** data from target backend before retrying. - Remove (or comment out) old backend from pdns.conf, and run - ``pdnsutil rectify-all-zones`` and ``pdnsutil check-all-zones`` to + ``pdnsutil zone rectify-all`` and ``pdnsutil zone check-all`` to make sure everything is OK. - If everything is OK, then go ahead to restart your PowerDNS service. Check logs to make sure everything went ok. diff --git a/docs/modes-of-operation.rst b/docs/modes-of-operation.rst index cbf013dc90..d62de1c9a3 100644 --- a/docs/modes-of-operation.rst +++ b/docs/modes-of-operation.rst @@ -215,7 +215,7 @@ In such cases, make sure to delete the zone contents to force a fresh retrieval. Finally, IXFR updates that "plug" Empty Non-Terminals do not yet remove -ENT records. A 'pdnsutil rectify-zone' may be required. +ENT records. A 'pdnsutil zone rectify' may be required. PowerDNS itself is currently only able to retrieve updates via IXFR. It cannot serve IXFR updates. @@ -263,7 +263,7 @@ There is no need to fill the account name out but it does help keep track of where a domain comes from. Additionally, if a secondary selects multiple autoprimaries for a zone based on the name of the primary, it also checks that the ``account`` field is the same for all. Adding a autoprimary can be done either directly in the database, -or by using the 'pdnsutil add-autoprimary' command. +or by using the 'pdnsutil autoprimary add' command. .. warning:: When a secondary receives notification while bootstrapping a new domain using autosecondary feature, it will send @@ -295,7 +295,7 @@ What you can accomplish using a Lua script: This script can be enabled like this:: - pdnsutil set-meta example.com LUA-AXFR-SCRIPT /path/to/lua/script.lua + pdnsutil metadata set example.com LUA-AXFR-SCRIPT /path/to/lua/script.lua .. warning:: The Lua script must both exist and be syntactically diff --git a/docs/running.rst b/docs/running.rst index 9c970dd8d1..0330c0b795 100644 --- a/docs/running.rst +++ b/docs/running.rst @@ -111,7 +111,7 @@ Backend manipulation ``pdnsutil`` ~~~~~~~~~~~~ -To perform zone and record changes using inbuilt tools, the ``pdnsutil`` command can be used. All available options are described in the online :doc:`manual page ` as well as in ``man pdnsutil``. +To perform zone and record changes using inbuilt tools, the :doc:`pdnsutil <../manpages/pdnsutil.1>` command can be used. All available options are described in the online :doc:`manual page <../manpages/pdnsutil.1>` as well as in ``man pdnsutil``. Running in the foreground ------------------------- diff --git a/docs/settings.rst b/docs/settings.rst index 4d8e4db2d5..7610766705 100644 --- a/docs/settings.rst +++ b/docs/settings.rst @@ -393,9 +393,9 @@ When a primary zone is created via the API, and the request does not specify a c - Default: ecdsa256 The default algorithm for creating zone keys when running -:doc:`pdnsutil add-zone-key ` if no algorithm is specified, +:doc:`pdnsutil zone add-key ` if no algorithm is specified, and also the algorithm that should be used for the KSK when running -:doc:`pdnsutil secure-zone ` or using the :doc:`Zone API endpoint ` +:doc:`pdnsutil zone secure ` or using the :doc:`Zone API endpoint ` to enable DNSSEC. Must be one of: * rsasha1 @@ -419,7 +419,7 @@ to enable DNSSEC. Must be one of: - Integer - Default: whichever is default for `default-ksk-algorithm`_ -The default keysize for the KSK generated with :doc:`pdnsutil secure-zone `. +The default keysize for the KSK generated with :doc:`pdnsutil zone secure `. Only relevant for algorithms with non-fixed keysizes (like RSA). .. _setting-default-publish-cdnskey: @@ -469,7 +469,7 @@ This value is used when a zone is created without providing a SOA record. @ is r Use this soa-edit value for all zones if no :ref:`metadata-soa-edit` metadata value is set. -This is used by :doc:`pdnsutil increase-serial `. +This is used by :doc:`pdnsutil zone increase-serial `. .. _setting-default-soa-edit-signed: @@ -528,9 +528,9 @@ TTL to use when none is provided. - Default: (empty) The default algorithm for creating zone keys when running -:doc:`pdnsutil add-zone-key ` if no algorithm is specified, +:doc:`pdnsutil zone add-key ` if no algorithm is specified, and also the algorithm that should be used for the ZSK when running -:doc:`pdnsutil secure-zone ` or using the :doc:`Zone API endpoint ` +:doc:`pdnsutil zone secure ` or using the :doc:`Zone API endpoint ` to enable DNSSEC. Must be one of: * rsasha1 @@ -554,7 +554,7 @@ to enable DNSSEC. Must be one of: - Integer - Default: 0 (automatic default for `default-zsk-algorithm`_) -The default keysize for the ZSK generated with :doc:`pdnsutil secure-zone `. +The default keysize for the ZSK generated with :doc:`pdnsutil zone secure `. Only relevant for algorithms with non-fixed keysizes (like RSA). .. _setting-delay-notifications: diff --git a/docs/tsig.rst b/docs/tsig.rst index 7b27c2d622..5f2d803614 100644 --- a/docs/tsig.rst +++ b/docs/tsig.rst @@ -42,8 +42,8 @@ Another way of importing and activating TSIG keys into the database is using .. code-block:: shell - pdnsutil import-tsig-key test hmac-md5 'kp4/24gyYsEzbuTVJRUMoqGFmN3LYgVDzJ/3oRSP7ys=' - pdnsutil activate-tsig-key powerdnssec.org test master + pdnsutil tsigkey import test hmac-md5 'kp4/24gyYsEzbuTVJRUMoqGFmN3LYgVDzJ/3oRSP7ys=' + pdnsutil tsigkey activate powerdnssec.org test primary To ease interoperability, the equivalent configuration above in BIND would look like this:: @@ -54,7 +54,7 @@ would look like this:: }; zone "powerdnssec.org" { - type master; + type primary; file "powerdnssec.org"; allow-transfer { key test.; }; }; @@ -88,8 +88,8 @@ This can also be done using .. code-block:: shell - pdnsutil import-tsig-key test hmac-md5 'kp4/24gyYsEzbuTVJRUMoqGFmN3LYgVDzJ/3oRSP7ys=' - pdnsutil activate-tsig-key powerdnssec.org test slave + pdnsutil tsigkey import test hmac-md5 'kp4/24gyYsEzbuTVJRUMoqGFmN3LYgVDzJ/3oRSP7ys=' + pdnsutil tsigkey activate powerdnssec.org test secondary This setup corresponds to the ``TSIG-ALLOW-AXFR`` access rule defined in the previous section. @@ -107,7 +107,7 @@ quite) similar to the following BIND statements:: }; zone "powerdnssec.org" { - type slave; + type secondary; masters { 127.0.0.1; }; file "powerdnssec.org"; }; diff --git a/docs/upgrading.rst b/docs/upgrading.rst index 4f6bf0ba31..68f35e6eb8 100644 --- a/docs/upgrading.rst +++ b/docs/upgrading.rst @@ -39,7 +39,7 @@ been implemented in the LMDB backend. LOC record parsing ^^^^^^^^^^^^^^^^^^ -The parsing and validation of LOC records is modified to be conforming to the `rfc:1876`. +The parsing and validation of LOC records is modified to be conforming to the :rfc:`1876`. This may cause records previously rejected to be accepted and vice versa. LUA records whitespace insertion @@ -62,18 +62,160 @@ ixfrdist IPv6 support ``ixfrdist`` now binds listening sockets with `IPV6_V6ONLY set`, which means that ``[::]`` no longer accepts IPv4 connections. If you want to listen on both IPv4 and IPv6, you need to add a line with ``0.0.0.0`` to the ``listen`` section of your ixfrdist configuration. -pdnsutil behaviour changes -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -A few changes of behaviour have been implemented in :doc:`pdnsutil `. - -* The ``add-zone-key`` command used to default to creating a ZSK, +pdnsutil syntax and behaviour changes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The :doc:`pdnsutil ` syntax has been overhauled in order to be more +orthogonal and consistent. Most commands will now take the form +``pdnsutil [arguments...]``, where ```` is a noun and +```` is a verb; a few commands which do not apply to any particular +object kind use only the verb. + +The old syntax is still recognized, so that existing scripts and finger memory +will keep working. However, you are advised to switch to the new command syntax, +using this conversion table: + ++-----------------------------------+--------------------------------+ +| Old syntax | New syntax | ++===================================+================================+ +| ``activate-tsig-key`` | ``tsigkey activate`` | ++-----------------------------------+--------------------------------+ +| ``activate-zone-key`` | ``zone activate-key`` | ++-----------------------------------+--------------------------------+ +| ``add-autoprimary`` | ``autoprimary add`` | ++-----------------------------------+--------------------------------+ +| ``add-meta`` | ``metadata add`` | ++-----------------------------------+--------------------------------+ +| ``add-record`` | ``rrset add`` | ++-----------------------------------+--------------------------------+ +| ``add-zone-key`` | ``zone add-key`` | ++-----------------------------------+--------------------------------+ +| ``change-secondary-zone-primary`` | ``zone change-primary`` | ++-----------------------------------+--------------------------------+ +| ``check-all-zones`` | ``zone check-all`` | ++-----------------------------------+--------------------------------+ +| ``check-zone`` | ``zone check`` | ++-----------------------------------+--------------------------------+ +| ``clear-zone`` | ``zone clear`` | ++-----------------------------------+--------------------------------+ +| ``create-secondary-zone`` | ``zone create-secondary`` | ++-----------------------------------+--------------------------------+ +| ``create-zone`` | ``zone create`` | ++-----------------------------------+--------------------------------+ +| ``deactivate-tsig-key`` | ``tsigkey deactivate`` | ++-----------------------------------+--------------------------------+ +| ``deactivate-zone-key`` | ``zone deactivate-key`` | ++-----------------------------------+--------------------------------+ +| ``delete-rrset`` | ``rrset delete`` | ++-----------------------------------+--------------------------------+ +| ``delete-tsig-key`` | ``tsigkey delete`` | ++-----------------------------------+--------------------------------+ +| ``delete-zone`` | ``zone delete`` | ++-----------------------------------+--------------------------------+ +| ``disable-dnssec`` | ``zone dnssec-disable`` | ++-----------------------------------+--------------------------------+ +| ``edit-zone`` | ``zone edit`` | ++-----------------------------------+--------------------------------+ +| ``export-zone-dnskey`` | ``zone export-dnskey`` | ++-----------------------------------+--------------------------------+ +| ``export-zone-ds`` | ``zone export-ds`` | ++-----------------------------------+--------------------------------+ +| ``export-zone-key`` | ``zone export-key`` | ++-----------------------------------+--------------------------------+ +| ``export-zone-key-pem`` | ``zone export-key-pem`` | ++-----------------------------------+--------------------------------+ +| ``generate-tsig-key`` | ``tsigkey generate`` | ++-----------------------------------+--------------------------------+ +| ``generate-zone-key`` | ``zone generate-key`` | ++-----------------------------------+--------------------------------+ +| ``get-meta`` | ``metadata get`` | ++-----------------------------------+--------------------------------+ +| ``hash-zone-record`` | ``rrset hash`` | ++-----------------------------------+--------------------------------+ +| ``import-tsig-key`` | ``tsigkey import`` | ++-----------------------------------+--------------------------------+ +| ``import-zone-key`` | ``zone import-key`` | ++-----------------------------------+--------------------------------+ +| ``import-zone-key-pem`` | ``zone import-key-pem`` | ++-----------------------------------+--------------------------------+ +| ``increase-serial`` | ``zone increase-serial`` | ++-----------------------------------+--------------------------------+ +| ``list-all-zones`` | ``zone list-all`` | ++-----------------------------------+--------------------------------+ +| ``list-autoprimaries`` | ``autoprimary list`` | ++-----------------------------------+--------------------------------+ +| ``list-keys`` | ``zone list-keys`` | ++-----------------------------------+--------------------------------+ +| ``list-member-zones`` | ``catalog list-members`` | ++-----------------------------------+--------------------------------+ +| ``list-tsig-keys`` | ``tsigkey list`` | ++-----------------------------------+--------------------------------+ +| ``list-zone`` | ``zone list`` | ++-----------------------------------+--------------------------------+ +| ``load-zone`` | ``zone load`` | ++-----------------------------------+--------------------------------+ +| ``publish-zone-key`` | ``zone publish-key`` | ++-----------------------------------+--------------------------------+ +| ``rectify-all-zones`` | ``zone rectify-all`` | ++-----------------------------------+--------------------------------+ +| ``rectify-zone`` | ``zone rectify`` | ++-----------------------------------+--------------------------------+ +| ``remove-autoprimary`` | ``autoprimary remove`` | ++-----------------------------------+--------------------------------+ +| ``remove-zone-key`` | ``zone remove-key`` | ++-----------------------------------+--------------------------------+ +| ``replace-rrset`` | ``rrset replace`` | ++-----------------------------------+--------------------------------+ +| ``secure-all-zones`` | ``zone secure-all`` | ++-----------------------------------+--------------------------------+ +| ``secure-zone`` | ``zone secure`` | ++-----------------------------------+--------------------------------+ +| ``set-account`` | ``zone set-account`` | ++-----------------------------------+--------------------------------+ +| ``set-catalog`` | ``catalog set`` | ++-----------------------------------+--------------------------------+ +| ``set-kind`` | ``zone set-kind`` | ++-----------------------------------+--------------------------------+ +| ``set-meta`` | ``metadata set`` | ++-----------------------------------+--------------------------------+ +| ``set-nsec3`` | ``zone set-nsec3`` | ++-----------------------------------+--------------------------------+ +| ``set-option`` | ``zone set-option`` | ++-----------------------------------+--------------------------------+ +| ``set-options-json`` | ``zone set-options-json`` | ++-----------------------------------+--------------------------------+ +| ``set-presigned`` | ``zone set-presigned`` | ++-----------------------------------+--------------------------------+ +| ``set-publish-cdnskey`` | ``zone set-publish-cdnskey`` | ++-----------------------------------+--------------------------------+ +| ``set-publish-cds`` | ``zone set-publish-cds`` | ++-----------------------------------+--------------------------------+ +| ``show-zone`` | ``zone show`` | ++-----------------------------------+--------------------------------+ +| ``unpublish-zone-key`` | ``zone unpublish-key`` | ++-----------------------------------+--------------------------------+ +| ``unset-nsec3`` | ``zone unset-nsec3`` | ++-----------------------------------+--------------------------------+ +| ``unset-presigned`` | ``zone unset-presigned`` | ++-----------------------------------+--------------------------------+ +| ``unset-publish-cdnskey`` | ``zone unset-publish-cdnskey`` | ++-----------------------------------+--------------------------------+ +| ``unset-publish-cds`` | ``zone unset-publish-cds`` | ++-----------------------------------+--------------------------------+ +| ``zonemd-verify-file`` | ``zone zonemd-verify-file`` | ++-----------------------------------+--------------------------------+ + +Commands not listed above have not changed syntax. + +A few changes of behaviour have been implemented as well: + +* The ``zone add-key`` command used to default to creating a ZSK, if no key type was given. This default has changed to KSK. -* The ``add-record``, ``delete-rrset``, ``edit-zone``, ``increase-serial`` and - ``replace-rrset`` operations will now refuse to work on secondary zones unless - the ``--force`` option is passed. -* When a zone gets created with either ``create-zone``, - ``create-secondary-zone`` or ``load-zone`` (if the zone wasn't existing +* The ``rrset add``, ``rrset delete``, ``rrset replace``, ``zone edit`` + and ``zone increase-serial`` operations will now refuse to work on secondary + zones unless the ``--force`` option is passed. +* When a zone gets created with either ``zone create``, + ``zone create-secondary`` or ``zone load`` (if the zone wasn't existing already), a :ref:`metadata-soa-edit-api` metadata with a value of ``DEFAULT`` will be added to the zone. * ``add-record`` and ``delete-rrset`` now treat all names as absolute. @@ -173,7 +315,7 @@ However, this feature interacts badly with handling of presigned zones. In version 4.5.0, this feature was accidentally broken in the implementation of the zone cache. In 4.6.0, this automatic conversion is fully removed. If you still have ``@`` signs in any SOA RNAMEs, 4.6.0 will serve those out literally. -You can find any stray ``@`` signs by running ``pdnsutil check-all-zones``. +You can find any stray ``@`` signs by running ``pdnsutil zone check-all``. New default NSEC3 parameters ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -183,7 +325,7 @@ Following `draft-ietf-dnsop-nsec3-guidance (Guidance for NSEC3 parameter setting SHA1 DSes ^^^^^^^^^ -``pdnsutil show-zone`` and ``pdnsutil export-zone-ds`` no longer emit SHA1 DS records, unless ``--verbose`` is in use. +``pdnsutil zone show`` and ``pdnsutil zone export-ds`` no longer emit SHA1 DS records, unless ``--verbose`` is in use. Privileged port binding in Docker ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -324,7 +466,7 @@ SOA autofilling (i.e. allowing incomplete SOAs in the database) and the API ``se * :ref:`setting-soa-retry-default` Replace them with :ref:`setting-default-soa-content`, but be aware that this will only be used at zone creation time. -Please run ``pdnsutil check-all-zones`` to check for incomplete SOAs. +Please run ``pdnsutil zone check-all`` to check for incomplete SOAs. The :ref:`setting-do-ipv6-additional-processing` setting was removed. IPv6 additional processing now always happens when IPv4 additional processing happens. @@ -349,7 +491,7 @@ On RHEL/CentOS 8, the gmysql backend now uses ``mariadb-connector-c`` instead of This change was made because the default MySQL implementation for RHEL8 is MariaDB, and MariaDB and MySQL cannot be installed in parallel due to conflicting RPM packages. The mariadb client lib will connect to your existing MySQL servers without trouble. -Unknown record encoding (`RFC 3597 `__) has become more strict as a result of the fixes for :doc:`PowerDNS Security Advisory 2020-05 <../security-advisories/powerdns-advisory-2020-05>`. Please use ``pdnsutil check-all-zones`` to review your zone contents. +Unknown record encoding (`RFC 3597 `__) has become more strict as a result of the fixes for :doc:`PowerDNS Security Advisory 2020-05 <../security-advisories/powerdns-advisory-2020-05>`. Please use ``pdnsutil zone check-all`` to review your zone contents. The previous set of indexes for the gsqlite3 backend was found to be poor. 4.3.1 ships a new schema, and a migration: @@ -424,7 +566,7 @@ Schema changes Implicit 5->7 algorithm upgrades ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Since version 3.0 (the first version of the PowerDNS Authoritative Server that supported DNSSEC signing), we have automatically, silently, upgraded algorithm 5 (RSASHA1) keys to algorithm 7 (RSASHA1-NSEC3-SHA1) when the user enabled NSEC3. This has been a source of confusion, and because of that, we introduced warnings for users of this feature in 4.0 and 4.1. To see if you are affected, run ``pdnsutil check-all-zones`` from version 4.0 or up. In this release, the automatic upgrade is gone, and affected zones will break if no action is taken. +Since version 3.0 (the first version of the PowerDNS Authoritative Server that supported DNSSEC signing), we have automatically, silently, upgraded algorithm 5 (RSASHA1) keys to algorithm 7 (RSASHA1-NSEC3-SHA1) when the user enabled NSEC3. This has been a source of confusion, and because of that, we introduced warnings for users of this feature in 4.0 and 4.1. To see if you are affected, run ``pdnsutil zone check-all`` from version 4.0 or up. In this release, the automatic upgrade is gone, and affected zones will break if no action is taken. .. _ixfr-in-corruption-4.3.0: @@ -438,7 +580,7 @@ You could accomplish that by deleting all records in the zone with an SQL query 4.2.X to 4.2.3 -------------- -Unknown record encoding (`RFC 3597 `__) has become more strict as a result of the fixes for :doc:`PowerDNS Security Advisory 2020-05 <../security-advisories/powerdns-advisory-2020-05>`. Please use ``pdnsutil check-all-zones`` to review your zone contents. +Unknown record encoding (`RFC 3597 `__) has become more strict as a result of the fixes for :doc:`PowerDNS Security Advisory 2020-05 <../security-advisories/powerdns-advisory-2020-05>`. Please use ``pdnsutil zone check-all`` to review your zone contents. 4.X.X to 4.2.2 -------------- @@ -465,7 +607,7 @@ You could accomplish that by deleting all records in the zone with an SQL query 4.1.X to 4.1.14 --------------- -Unknown record encoding (`RFC 3597 `__) has become more strict as a result of the fixes for :doc:`PowerDNS Security Advisory 2020-05 <../security-advisories/powerdns-advisory-2020-05>`. Please use ``pdnsutil check-all-zones`` to review your zone contents. +Unknown record encoding (`RFC 3597 `__) has become more strict as a result of the fixes for :doc:`PowerDNS Security Advisory 2020-05 <../security-advisories/powerdns-advisory-2020-05>`. Please use ``pdnsutil zone check-all`` to review your zone contents. 4.1.0 to 4.1.1 -------------- @@ -625,4 +767,4 @@ MBOXFW records. Thus, make sure to clean up the records in the DB. In version 3.X, the PowerDNS Authoritative Server silently ignored records that have a 'priority' field (like MX or SRV), but where one was not in the database. -In 4.X, :doc:`pdnsutil check-zone ` will complain about this. +In 4.X, :doc:`pdnsutil zone check ` will complain about this. diff --git a/docs/views.rst b/docs/views.rst index 45c68fbc52..0c50f0ed16 100644 --- a/docs/views.rst +++ b/docs/views.rst @@ -119,14 +119,14 @@ the rest of the Internet. Let's start by defining the specific networks:: - pdnsutil set-network 10.0.0.0/8 internal - pdnsutil set-network 172.16.0.0/12 internal - pdnsutil set-network 192.168.0.0/16 internal - pdnsutil set-network fc00::/7 internal + pdnsutil network set 10.0.0.0/8 internal + pdnsutil network set 172.16.0.0/12 internal + pdnsutil network set 192.168.0.0/16 internal + pdnsutil network set fc00::/7 internal - pdnsutil set-network 198.51.100.0/24 trusted - pdnsutil set-network 203.0.113.0/24 trusted - pdnsutil set-network 2001:db8::/32 trusted + pdnsutil network set 198.51.100.0/24 trusted + pdnsutil network set 203.0.113.0/24 trusted + pdnsutil network set 2001:db8::/32 trusted Once these commands have been run, queries originating from these particular networks will select either the "internal" or "trusted" view, while queries @@ -135,7 +135,7 @@ may consider an always-existing default (nameless) view. You can check the result of these commands with:: - $ pdnsutil list-networks + $ pdnsutil network list 10.0.0.0/8 internal 172.16.0.0/12 internal 192.168.0.0/16 internal @@ -149,19 +149,19 @@ outcome when resolving domain queries. Let's differentiate these views now:: - pdnsutil view-add-zone internal example.com..internal - pdnsutil view-add-zone internal example2.com..secret + pdnsutil views add-zone internal example.com..internal + pdnsutil views add-zone internal example2.com..secret - pdnsutil view-add-zone trusted example.com..trusted + pdnsutil views add-zone trusted example.com..trusted -Note that the `view-add-zone` command does not create any zone! You will need +Note that the `views add-zone` command does not create any zone! You will need to create these zones, like you would do for any other "regular" zone:: - pdnsutil create-zone example.com..internal - pdnsutil create-zone example2.com..secret - pdnsutil create-zone example.com..trusted + pdnsutil zone create example.com..internal + pdnsutil zone create example2.com..secret + pdnsutil zone create example.com..trusted -and then use `load-zone`, `edit-zone`, or `add-record` to add contents to these +and then use `zone load`, `zone edit`, or `rrset add` to add contents to these zones. With these settings in place, queries for the `example.com.` zone will be @@ -179,13 +179,13 @@ As seen in this example, a given view may cause multiple zones to be resolved differently. At any time, you can check which views are setup, and the details of a given view:: - $ pdnsutil list-views + $ pdnsutil views list-all internal trusted - $ pdnsutil list-view internal + $ pdnsutil views list internal example.com..internal example2.com..secret - $ pdnsutil list-view trusted + $ pdnsutil views list trusted example.com..trusted Bind configuration adaptation @@ -215,14 +215,14 @@ https://www.zytrax.com/books/dns/ch7/view.html:: The equivalent PowerDNS setup would be:: - pdnsutil set-network 192.168.23.0/24 trusted - pdnsutil set-network 0.0.0.0/0 badguys + pdnsutil network set 192.168.23.0/24 trusted + pdnsutil network set 0.0.0.0/0 badguys - pdnsutil view-add-zone trusted primary.example.com..internal - pdnsutil view-add-zone badguys primary.example.com..external + pdnsutil views add-zone trusted primary.example.com..internal + pdnsutil views add-zone badguys primary.example.com..external - pdnsutil load-zone example.com..internal internal/primary.example.com - pdnsutil load-zone example.com..external external/primary.example.com + pdnsutil zone load example.com..internal internal/primary.example.com + pdnsutil zone load example.com..external external/primary.example.com .. _views-catalog-zones: