From: Pieter Lexis Date: Wed, 17 Mar 2021 08:39:44 +0000 (+0100) Subject: docs: Remove SQL statements from gsql docs X-Git-Tag: dnsdist-1.6.0-rc1~40^2~2 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=6b0f8acfe61f54fa2d0975d5d0c8041b45500bdc;p=thirdparty%2Fpdns.git docs: Remove SQL statements from gsql docs --- diff --git a/docs/backends/generic-sql.rst b/docs/backends/generic-sql.rst index b056d607ba..2098f6d2b8 100644 --- a/docs/backends/generic-sql.rst +++ b/docs/backends/generic-sql.rst @@ -7,14 +7,12 @@ on any SQL database of your choosing. Because all database schemas will be different, a generic backend is needed to cover all needs. .. warning:: - 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. + It is highly recommended to not use raw SQL commands to manipulate records in the database. + Either use the :doc:`REST-API <../http-api/index>` or (as shown in the examples here) :doc:`../manpages/pdnsutil.1`. + + If raw SQL is used, ensure that record and zone names are **never** terminated with a trailing '.'. + The only exception is a root-zone, this must have the name of '.' (no quotes). -.. note:: - A root zone or record should have a name of '.' - (no quotes). This is the only exception to the 'no terminating dot in - SQL storage' rule. Basic functionality ------------------- @@ -25,24 +23,19 @@ describes the :doc:`../modes-of-operation`. Native operation ^^^^^^^^^^^^^^^^ -To add a domain, issue the following: - -.. code-block:: SQL +To add a domain, issue the following:: - INSERT INTO domains (name, type) VALUES ('example.com', 'NATIVE'); + pdnsutil create-zone example.com -The records table can now be filled by with the domain_id set to the id -of the domains table row just inserted. +Records can now be added using ``pdnsutil add-record`` or ``pdnsutil edit-zone``. Slave operation ^^^^^^^^^^^^^^^ These backends are fully slave capable. To become a slave of the -'example.com' domain, execute this: +'example.com' domain, using 198.51.100.6 as the master execute this:: -.. code-block:: SQL - - INSERT INTO domains (name, master, type) VALUES ('example.com', '198.51.100.6', 'SLAVE'); + pdnsutil create-slave-zone 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 @@ -69,24 +62,20 @@ has been checked, it will not be checked before its SOA refresh timer has expired. Domains whose status is unknown get checked every 60 seconds by default. -PowerDNS has support for multiple masters per zone, separate master IP -addresses by commas: - -.. code-block:: SQL +PowerDNS has support for multiple masters per zone, and also port numbers for these masters:: - INSERT INTO domains (name, master, type) VALUES ('example.com', '198.51.100.6, 2001:0DB8:15:4AF::4', 'SLAVE'); + pdnsutil create-slave-zone example.com 198.51.100.6 2001:0DB8:15:4AF::4 + pdnsutil create-slave-zone example.net 198.51.100.20:5301 [2001:0DB8:11:6E::4]:54 Superslave operation ^^^^^^^^^^^^^^^^^^^^ -To configure a supermaster with IP address 203.0.113.53 which lists this -installation as 'autoslave.example.com', issue the following: - -.. code-block:: SQL +To configure a :ref:`supermaster ` with IP address 203.0.113.53 which lists this +installation as 'autoslave.example.com', issue the following:: - INSERT INTO supermasters VALUES ('203.0.113.53', 'autoslave.example.com', 'internal'); + pdnsutil add-supermaster 203.0.113.53 autoslave.example.com internal -From now on, valid notifies from 203.0.113.53 that list a NS record +From now on, valid notifies from 203.0.113.53 for which the zone lists an NS record containing 'autoslave.example.com' will lead to the provisioning of a slave domain under the account 'internal'. See :ref:`supermaster-operation` for details. @@ -97,14 +86,10 @@ Master operation The generic SQL backend is fully master capable with automatic discovery of serial changes. Raising the serial number of a domain suffices to trigger PowerDNS to send out notifications. To configure a domain for -master operation instead of the default native replication, issue: +master operation instead of the default native replication, issue:: -.. code-block:: SQL - - INSERT INTO domains (name, type) VALUES ('example.com', 'MASTER'); - -Make sure that the assigned id in the domains table matches the -domain_id field in the records table! + pdnsutil create-zone example.com + pdnsutil set-kind example.com MASTER .. _generic-sql-disabled-data: @@ -116,6 +101,8 @@ setting "disabled" to ``1`` (for PostgreSQL: ``true``). By extension, when the SOA record for a domain is disabled, the entire domain is considered to be disabled. +This value cannot be set with ``pdnsutil``. + Effects: the record (or domain, respectively) will not be visible to DNS clients. The REST API will still see the record (or domain). Even if a domain is disabled, slaving still works. Slaving considers a disabled @@ -135,6 +122,9 @@ to 'yes'. Rules for filling out DNSSEC fields ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. note:: + This section is only relevant for user 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 transfer, and also by running ``pdnsutil rectify-zone``. @@ -192,6 +182,8 @@ on the basis of %-placeholders. To see the default queries for a backend, run ``pdns_server --launch=BACKEND --config=default``. +This section is useful for users who have their own database schema and wish to have PowerDNS use the existing database. + Regular Queries ^^^^^^^^^^^^^^^ diff --git a/docs/modes-of-operation.rst b/docs/modes-of-operation.rst index 867cdc2614..df7b2f554e 100644 --- a/docs/modes-of-operation.rst +++ b/docs/modes-of-operation.rst @@ -242,15 +242,9 @@ on SOA - Change incoming SOA serial number to a YYYYMMDDnn format - Ensure consistent NS RRset - Timestamp the zone transfer with a TXT record -To enable a Lua script for a particular slave zone, determine the -``domain_id`` for the zone from the ``domains`` table, and add a row to -the ``domainmetadata`` table for the domain. Supposing the domain we -want has an ``id`` of 3, the following SQL statement will enable the Lua -script ``my.lua`` for that domain: +This script can be enabled like this:: -.. code-block:: SQL - - INSERT INTO domainmetadata (domain_id, kind, content) VALUES (3, "LUA-AXFR-SCRIPT", "/lua/my.lua"); + pdnsutil set-meta example.com LUA-AXFR-SCRIPT /path/to/lua/script.lua .. warning:: The Lua script must both exist and be syntactically