From 2694e4b4a1dbc85b554703c5fea7b3fa65b766b0 Mon Sep 17 00:00:00 2001 From: Robin Geuze Date: Wed, 18 Sep 2019 18:25:42 +0200 Subject: [PATCH] Remove the oracle backends documentation --- docs/backends/generic-oracle.rst | 72 --- docs/backends/oracle.rst | 724 ------------------------------- 2 files changed, 796 deletions(-) delete mode 100644 docs/backends/generic-oracle.rst delete mode 100644 docs/backends/oracle.rst diff --git a/docs/backends/generic-oracle.rst b/docs/backends/generic-oracle.rst deleted file mode 100644 index 59fa2e74c..000000000 --- a/docs/backends/generic-oracle.rst +++ /dev/null @@ -1,72 +0,0 @@ -Generic Oracle backend -====================== - -* Native: Yes -* Master: Yes -* Slave: Yes -* Superslave: Yes -* Autoserial: No -* Case: All lower -* DNSSEC: Yes (set ``goracle-dnssec``) -* Disabled data: Yes -* Comments: Yes -* Module name: goracle -* Launch name: ``goracle`` - -The Generic Oracle Backend is a :doc:`generic-sql`. The default setup conforms to the -following schema, which you should add to an Oracle database. You may -need or want to add ``namespace`` statements. - -.. warning:: - The Oracle backends depend on non-free software that requires significant - resources from us to support. Consequently, we can not provide free - support to users of this backend. Before deploying PowerDNS with an Oracle - database, please head to `our commercial support page - `_. - -Below, you will find the schema for 4.2. If you are using 4.1 or earlier, please find `the 4.1 schema on GitHub `_. - -.. literalinclude:: ../../modules/goraclebackend/schema.goracle.sql - :language: SQL - -This schema contains all elements needed for master, slave and -superslave operation. - -Inserting records is a bit different compared to MySQL and PostgreSQL, -you should use: - -.. code-block:: SQL - - INSERT INTO domains (id,name,type) VALUES (domains_id_sequence.nextval, 'example.net', 'NATIVE'); - -Settings --------- - -.. _setting-goracle-tnsname: - -``goracle-tnsname`` -^^^^^^^^^^^^^^^^^^^ - -Which TNSNAME the Generic Oracle Backend should be connecting to. There -are no ``goracle-dbname``, ``goracle-host`` or ``goracle-port`` -settings, their equivalent is in ``/etc/tnsnames.ora``. - -.. _setting-goracle-dnssec: - -``goracle-dnssec`` -^^^^^^^^^^^^^^^^^^ - -Enable DNSSEC processing for this backend. Default=no. - -Caveats -------- - -Password Expiry -^^^^^^^^^^^^^^^ - -When your password is about to expire, and logging into oracle warns -about this, the Generic Oracle backend can no longer login, and will a -OCILogin2 warning. - -To work around this, either update the password in time or remove -expiration from the account used. diff --git a/docs/backends/oracle.rst b/docs/backends/oracle.rst deleted file mode 100644 index ba9b7c34b..000000000 --- a/docs/backends/oracle.rst +++ /dev/null @@ -1,724 +0,0 @@ -Oracle backend -============== - -* Native: Yes -* Master: Yes -* Slave: Yes -* Superslave: Yes -* Autoserial: No -* DNSSEC: Yes -* Comments: No -* Module name: oracle -* Launch name: ``oracle`` - -This is the Oracle Database backend with easily configurable SQL statements, allowing you to graft - -.. warning:: - The Oracle backends depend on non-free software that requires significant - resources from us to support. Consequently, we can not provide free - support to users of this backend. Before deploying PowerDNS with an Oracle - database, please head to `our commercial support page - `_. - -PowerDNS functionality onto any Oracle database of your choosing. - -The Oracle backend is difficult, and possibly illegal, to distribute in -binary form. To use it, you will probably need to compile PowerDNS from -source. OCI headers are expected in ``$ORACLE_HOME/rdbms/public``, and -OCI libraries in ``$ORACLE_HOME/lib``. That is where they should be with -a working installation of the full Oracle Database client. Oracle -InstantClient should work as well, but you will need to make the -libraries and headers available in appropriate paths. - -This backend uses two kinds of database connections. First, it opens a -session pool. Connections from this pool are used only for queries -reading DNS data from the database. Second, it opens normal (non-pooled) -connections on demand for any kind of write access. The reason for this -split is to allow redundancy by replication. Each DNS frontend server -can have a local read-only replicated instance of your database. Open -the session pool to the local replicated copy, and all data will be -available with high performance, even if the main database goes down. -The writing connections should go directly to the main database. - -Of course, if you do not require this kind of redundancy, or want to -avoid the substantial Oracle Database licensing costs, all connections -can just go to the same database with the same credentials. Also, the -write connections should be entirely unnecessary if you do not plan to -use either master or slave mode. - -Configuration Parameters ------------------------- - -.. _setting-oracle-pool: - -``oracle-pool-database``, ``oracle-pool-username``, ``oracle-pool-password`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The database to use for read access. OracleBackend will try to create a -session pool, so make sure this database user has the necessary -permissions. If your connection requires environment variables to be -set, e.g. ``ORACLE_HOME``, ``NLS_LANG``, or ``LD_LIBRARY_PATH``, make -sure these are set when PowerDNS runs. ``/etc/default/pdns`` might help. - -.. _setting-oracle-master: - -``oracle-master-database``, ``oracle-master-username``, ``oracle-master-password`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The database to use for write access. These are normal connections, not -a session pool. The backend may open more than one at a time. - -.. _setting-oracle-session: - -``oracle-session-min``, ``oracle-session-max``, ``oracle-session-inc`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Parameters for the connection pool underlying the session pool. OCI will -open ``session-min`` connections at startup, and open more connections -as needed, ``session-inc`` at a time, until ``session-max`` connections -are open. - -.. _setting-oracle-nameserver-name: - -``oracle-nameserver-name`` -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This can be set to an arbitrary string that will be made available in -the optional bind variable ``:nsname`` for all SQL statements. You can -use this to run multiple PowerDNS instances off the same database, while -serving different zones. - -There are many more options that are used to define the different SQL -statements. These will be discussed after the reference database schema -has been explained. - -The Database Schema -------------------- - -You can find an example database schema in ``schema.sql`` in the -PowerDNS source distribution. It is intended more as a starting point to -come up with a schema that works well for your organisation, than as -something you should run as it is. As long as the semantics of the SQL -statements still work out, you can store your DNS data any way you like. - -You should read this while having ``schema.sql`` to hand. Columns will -not be specifically explained where their meaning is obvious. - -.. note:: - All FQDNs should be specified in lower case and without a - trailing dot. Where things are lexicographically compared or sorted, - make sure a sane ordering is used. - ``'NLS_LANG=AMERICAN_AMERICA.AL32UTF8'`` should generally work well - enough; when in doubt, enforce a plain ordering with - ``"NLSSORT(value, 'NLS_SORT = BINARY')"``. - -Zones Table -~~~~~~~~~~~ - -This table lists the zones for which PowerDNS is supposed to be an -authoritative nameserver, plus a small amount of information related to -master/slave mode. - -name -^^^^ - -The FQDN of the zone apex, e.g. 'example.com'. - -type -^^^^ - -Describes how PowerDNS should host the zone. Valid values are 'NATIVE', -'MASTER', and 'SLAVE'. PowerDNS acts as an authoritative nameserver for -the zone in all modes. In slave mode, it will additionally attempt to -acquire the zone's content from a master server. In master mode, it will -additionally send 'NOTIFY' packets to other nameservers for the zone -when its content changes. - -**Tip**: There is a global setting to make PowerDNS send 'NOTIFY' -packets in slave mode. - -last\_check -^^^^^^^^^^^ - -This value, updated by PowerDNS, is the unix timestamp of the last -successful attempt to check this zone for freshness on the master. - -refresh -^^^^^^^ - -The number of seconds PowerDNS should wait after a successful freshness -check before performing another one. This value is also found in the -zone's SOA record. You may want to make sure to put the same thing in -both places. - -serial -^^^^^^ - -The serial of the version of the zone's content we are hosting now. This -value is also found in the zone's SOA record. You may want to make sure -to put the same thing in both places. - -notified\_serial -^^^^^^^^^^^^^^^^ - -The latest serial for which we have sent ``NOTIFY`` packets. Updated by -PowerDNS. - -The Zonemasters and ZoneAlsoNotify Tables -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -These are lists of hosts PowerDNS will interact with for a zone in -master/slave mode. 'Zonemasters' lists the hosts PowerDNS will attempt -to pull zone transfers from, and accept 'NOTIFY' packets from. -'ZoneAlsoNotify' lists hosts PowerDNS will send 'NOTIFY' packets to, in -addition to any hosts that have NS records. - -Host entries can be IPv4 or IPv6 addresses, in string representation. If -you need to specify a port, use ``192.0.2.4:5300`` notation for IPv4 and -brackets for IPv6: ``[2001:db8::1234]:5300``. - -The Supermasters Table -~~~~~~~~~~~~~~~~~~~~~~ - -In superslave mode, PowerDNS can accept 'NOTIFY' packets for zones that -have not been defined in the zone table yet. PowerDNS will then create -an entry for the zone and attempt a zone transfer. This table defines -the list of acceptable sources for supernotifications. - -name -^^^^ - -An identifying string for this entry. Only used for logging. - -ip -^^ - -The alleged originating IP address of the notification. - -nameserver -^^^^^^^^^^ - -The FQDN of an authoritative nameserver. - -A supernotification will be accepted if an entry is found such that the -notification came from 'ip' and 'nameserver' appears in an NS record for -that zone. - -The ZoneMetadata Table -~~~~~~~~~~~~~~~~~~~~~~ - -This is a per-zone key-value store for various things PowerDNS needs to -know that are not part of the zone's content or handled by other tables. -Depending on your needs, you may not want this to exist as an actual -table, but simulate this in PL/SQL instead. - -The currently defined metadata types are: - -'PRESIGNED' -^^^^^^^^^^^ - -If set to 1, PowerDNS should assume that DNSSEC signatures for this zone -exist in the database and use them instead of signing records itself. -For a slave zone, this will also signal to the master that we want -DNSSEC records when attempting a zone transfer. - -'NSEC3PARAM' -^^^^^^^^^^^^ - -The NSEC3 hashing parameters for the zone. - -'TSIG-ALLOW-AXFR' -^^^^^^^^^^^^^^^^^ - -The value is the name of a TSIG key. A client will be allowed to AXFR -from us if the request is signed with that key. - -'AXFR-MASTER-TSIG' -^^^^^^^^^^^^^^^^^^ - -The value is the name of a TSIG key. Outgoing ``NOTIFY`` packets for -this zone will be signed with that key. - -The Tables for Cryptographic Keys -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -We have two of them: 'TSIGKeys' for symmetric TSIG keys, and -'ZoneDNSKeys' for DNSSEC signing keys. - -The Records Table -~~~~~~~~~~~~~~~~~ - -The actual DNS zone contents are stored here. - -zone\_id -^^^^^^^^ - -The zone this records belongs to. Normally, this is obvious. When you -are dealing with zone delegations, you have to insert some records into -the parent zone of their actual zone. See also ``auth``. - -fqdn -^^^^ - -The owner name of this record. Again, this is lower case and without a -trailing dot. - -revfqdn -^^^^^^^ - -This should be a string that consists of the labels of the owner name, -in reverse order, with spaces instead of dots separating them, for -example: - -:: - - 'www.example.com' => 'com example www' - -This is used as a quick and dirty way to get canonical zone ordering. -You can chose a more correct and much more complicated implementation -instead if you prefer. In the reference schema, this is automatically -set by a trigger. - -fqdnhash -^^^^^^^^ - -The NSEC3 hash of the owner name. The reference schema provides code and -a trigger to calculate this, but they are not production quality. The -recommendation is to load the dnsjava classes into your database and use -their facilities for dealing with DNS names and NSEC3 hashes. - -ttl -^^^ - -The TTL for the record set. This should be the same for all members of a -record set, but PowerDNS will quietly use the minimum if it encounters -different values. - -type -^^^^ - -The type of the record, as a canonical identification string, e.g. -'AAAA' or 'MX'. You can set this and 'content' NULL to indicate a name -that exists, but doesn't carry any record (a so called empty -non-terminal) for NSEC/NSEC3 ordering purposes. - -content -^^^^^^^ - -The data part of the DNS record, in canonical string representation, -except that if this includes FQDNs, they should be specified without a -trailing dot. - -auth -^^^^ - -0 or 1 depending on whether this record is an authoritative member of -the zone specified in ``zone_id``. These are the rules for determining -that: A record is an authoritative member of the zone its owner name -belongs to, except for DS records, which are authoritative members of -the parent zone. Delegation records, that is, NS records and related -A/AAAA glue records, are additionally non-authoritative members of the -parent zone. - -PowerDNS has a function to automatically set this. OracleBackend doesn't -support that. Do it in the database. - -The SQL Statements -~~~~~~~~~~~~~~~~~~ - -Fetching DNS records -^^^^^^^^^^^^^^^^^^^^ - -There are five queries to do this. They all share the same set of return -columns: - -- fqdn: The owner name of the record. -- ttl: The TTL of the record set. -- type: The type of the record. -- content: The content of the record. -- zone\_id: The numerical identifier of the zone the record belongs to. - A record can belong to two zones (delegations/glue), in which case it - may be returned twice. -- auth: 1 or 0 depending on the zone membership (authoritative or not). - -Record sets (records for the same name of the same type) must appear -consecutively, which means **ORDER BY** clauses are needed in some -places. Empty non-terminals should be suppressed. - -The queries differ in which columns are restricted by 'WHERE' clauses: - -oracle-basic-query -'''''''''''''''''' - -Looking for records based on owner name and type. Default: - -.. code-block:: SQL - - SELECT fqdn, ttl, type, content, zone_id, last_change, auth - FROM Records - WHERE type = :type AND fqdn = lower(:name) - -oracle-basic-id-query -''''''''''''''''''''' - -Looking for records from one zone based on owner name and type. Default: - -.. code-block:: SQL - - SELECT fqdn, ttl, type, content, zone_id, last_change, auth - FROM Records - WHERE type = :type AND fqdn = lower(:name) AND zone_id = :zoneid - -oracle-any-query -'''''''''''''''' - -Looking for records based on owner name. Default: - -.. code-block:: SQL - - SELECT fqdn, ttl, type, content, zone_id, last_change, auth - FROM Records - WHERE fqdn = lower(:name) - AND type IS NOT NULL - ORDER BY type - -oracle-any-id-query -''''''''''''''''''' - -Looking for records from one zone based on owner name. Default: - -.. code-block:: SQL - - SELECT fqdn, ttl, type, content, zone_id, last_change, auth - FROM Records - WHERE fqdn = lower(:name) - AND zone_id = :zoneid - AND type IS NOT NULL - ORDER BY type - -oracle-list-query -''''''''''''''''' - -Looking for all records from one zone. Default: - -.. code-block:: SQL - - SELECT fqdn, ttl, type, content, zone_id, last_change, auth - FROM Records - WHERE zone_id = :zoneid - AND type IS NOT NULL - ORDER BY fqdn, type - -Zone Metadata and TSIG -^^^^^^^^^^^^^^^^^^^^^^ - -oracle-get-zone-metadata-query -'''''''''''''''''''''''''''''' - -Fetch the content of the metadata entries of type ':kind' for the zone -called ':name', in their original order. Default: - -.. code-block:: SQL - - SELECT md.meta_content - FROM Zones z JOIN ZoneMetadata md ON z.id = md.zone_id - WHERE z.name = lower(:name) AND md.meta_type = :kind - ORDER BY md.meta_ind - -oracle-del-zone-metadata-query -'''''''''''''''''''''''''''''' - -Delete all metadata entries of type ':kind' for the zone called ':name'. -You can skip this if you do not plan to manage zones with the -``pdnsutil`` tool. Default: - -.. code-block:: SQL - - DELETE FROM ZoneMetadata md - WHERE zone_id = (SELECT id FROM Zones z WHERE z.name = lower(:name)) - AND md.meta_type = :kind - -oracle-set-zone-metadata-query -'''''''''''''''''''''''''''''' - -Create a metadata entry. You can skip this if you do not plan to manage -zones with the ``pdnsutil`` tool. Default: - -.. code-block:: SQL - - INSERT INTO ZoneMetadata (zone_id, meta_type, meta_ind, meta_content) - VALUES ( - (SELECT id FROM Zones WHERE name = lower(:name)), - :kind, :i, :content - ) - -oracle-get-tsig-key-query -''''''''''''''''''''''''' - -Retrieved the TSIG key specified by ':name'. Default: - -.. code-block:: SQL - - SELECT algorithm, secret - FROM TSIGKeys - WHERE name = :name - -DNSSEC -^^^^^^ - -oracle-get-zone-keys-query -'''''''''''''''''''''''''' - -Retrieve the DNSSEC signing keys for a zone. Default: - -.. code-block:: SQL - - SELECT k.id, k.flags, k.active, k.keydata - FROM ZoneDNSKeys k JOIN Zones z ON z.id = k.zone_id - WHERE z.name = lower(:name) - -oracle-del-zone-key-query -''''''''''''''''''''''''' - -Delete a DNSSEC signing key. You can skip this if you do not plan to -manage zones with the ``pdnsutil`` tool. Default: - -.. code-block:: SQL - - DELETE FROM ZoneDNSKeys WHERE id = :keyid - -oracle-add-zone-key-query -''''''''''''''''''''''''' - -Add a DNSSEC signing key. You can skip this if you do not plan to manage -zones with the ``pdnsutil`` tool. Default: - -.. code-block:: SQL - - INSERT INTO ZoneDNSKeys (id, zone_id, flags, active, keydata) - VALUES ( - zonednskeys_id_seq.NEXTVAL, - (SELECT id FROM Zones WHERE name = lower(:name)), - :flags, - :active, - :content - ) RETURNING id INTO :keyid - -oracle-set-zone-key-state-query -''''''''''''''''''''''''''''''' - -Enable or disable a DNSSEC signing key. You can skip this if you do not -plan to manage zones with the **pdnsutil** tool. Default: - -.. code-block:: SQL - - UPDATE ZoneDNSKeys SET active = :active WHERE id = :keyid - -oracle-prev-next-name-query -''''''''''''''''''''''''''' - -Determine the predecessor and successor of an owner name, in canonical -zone ordering. See the reference implementation for the quick and dirty -way, and the RFCs for the full definition of canonical zone ordering. - -This statement is a PL/SQL block that writes into two of the bind -variables, not a query. - -Default: - -.. code-block:: SQL - - BEGIN - get_canonical_prev_next(:zoneid, :name, :prev, :next); - END; - -oracle-prev-next-hash-query -''''''''''''''''''''''''''' - -Given an NSEC3 hash, this call needs to return its predecessor and -successor in NSEC3 zone ordering into ``:prev`` and ``:next``, and the -FQDN of the predecessor into ``:unhashed``. Default: - -.. code-block:: SQL - - BEGIN - get_hashed_prev_next(:zoneid, :hash, :unhashed, :prev, :next); - END; - -Incoming AXFR -^^^^^^^^^^^^^ - -oracle-zone-info-query -'''''''''''''''''''''' - -Get some basic information about the named zone before doing -master/slave things. Default: - -.. code-block:: SQL - - SELECT id, name, type, last_check, serial, notified_serial - FROM Zones - WHERE name = lower(:name) - -oracle-delete-zone-query -'''''''''''''''''''''''' - -Delete all records for a zone in preparation for an incoming zone -transfer. This happens inside a transaction, so if the transfer fails, -the old zone content will still be there. Default: - -.. code-block:: SQL - - DELETE FROM Records WHERE zone_id = :zoneid - -oracle-insert-record-query -'''''''''''''''''''''''''' - -Insert a record into the zone during an incoming zone transfer. This -happens inside the same transaction as delete-zone, so we will not end -up with a partially transferred zone. Default: - -.. code-block:: SQL - - INSERT INTO Records (id, fqdn, zone_id, ttl, type, content) - VALUES (records_id_seq.NEXTVAL, lower(:name), :zoneid, :ttl, :type, :content) - -oracle-finalize-axfr-query -'''''''''''''''''''''''''' - -A block of PL/SQL to be executed after a zone transfer has successfully -completed, but before committing the transaction. A good place to locate -empty non-terminals, set the ``auth`` bit and NSEC3 hashes, and -generally do any post-processing your schema requires. The do-nothing -default: - -.. code-block:: SQL - - DECLARE - zone_id INTEGER := :zoneid; - BEGIN - NULL; - END; - -Master/Slave Stuff -^^^^^^^^^^^^^^^^^^ - -oracle-unfresh-zones-query -'''''''''''''''''''''''''' - -Return a list of zones that need to be checked and their master servers. -Return multiple rows, identical except for the master address, for zones -with more than one master. Default: - -.. code-block:: SQL - - SELECT z.id, z.name, z.last_check, z.serial, zm.master - FROM Zones z JOIN Zonemasters zm ON z.id = zm.zone_id - WHERE z.type = 'SLAVE' - AND (z.last_check IS NULL OR z.last_check + z.refresh < :ts) - ORDER BY z.id - -oracle-zone-set-last-check-query -'''''''''''''''''''''''''''''''' - -Set the last check timestamp after a successful check. Default: - -.. code-block:: SQL - - UPDATE Zones SET last_check = :lastcheck WHERE id = :zoneid - -oracle-updated-masters-query -'''''''''''''''''''''''''''' - -Return a list of zones that need to have ``NOTIFY`` packets sent out. -Default: - -.. code-block:: SQL - - SELECT id, name, serial, notified_serial - FROM Zones - WHERE type = 'MASTER' - AND (notified_serial IS NULL OR notified_serial < serial) - -oracle-zone-set-notified-serial-query -''''''''''''''''''''''''''''''''''''' - -Set the last notified serial after packets have been sent. Default: - -.. code-block:: SQL - - UPDATE Zones SET notified_serial = :serial WHERE id = :zoneid - -oracle-also-notify-query -'''''''''''''''''''''''' - -Return a list of hosts that should be notified, in addition to any -nameservers in the NS records, when sending ``NOTIFY`` packets for the -named zone. Default: - -.. code-block:: SQL - - SELECT an.hostaddr - FROM Zones z JOIN ZoneAlsoNotify an ON z.id = an.zone_id - WHERE z.name = lower(:name) - -oracle-zone-masters-query -''''''''''''''''''''''''' - -Return a list of masters for the zone specified by id. Default: - -.. code-block:: SQL - - SELECT master - FROM Zonemasters - WHERE zone_id = :zoneid - -oracle-is-zone-master-query -''''''''''''''''''''''''''' - -Return a row if the specified host is a registered master for the named -zone. Default: - -.. code-block:: SQL - - SELECT zm.master - FROM Zones z JOIN Zonemasters zm ON z.id = zm.zone_id - WHERE z.name = lower(:name) AND zm.master = :master - -Superslave Stuff -^^^^^^^^^^^^^^^^ - -oracle-accept-supernotification-query -''''''''''''''''''''''''''''''''''''' - -If a supernotification should be accepted from ':ip', for the master -nameserver ':ns', return a label for this supermaster. Default: - -.. code-block:: SQL - - SELECT name - FROM Supermasters - WHERE ip = :ip AND nameserver = lower(:ns) - -oracle-insert-slave-query -''''''''''''''''''''''''' - -A supernotification has just been accepted, and we need to create an -entry for the new zone. Default: - -.. code-block:: SQL - - INSERT INTO Zones (id, name, type) - VALUES (zones_id_seq.NEXTVAL, lower(:zone), 'SLAVE') - RETURNING id INTO :zoneid - -oracle-insert-master-query -'''''''''''''''''''''''''' - -We need to register the first master server for the newly created zone. -Default: - -.. code-block:: SQL - - INSERT INTO Zonemasters (zone_id, master) - VALUES (:zoneid, :ip) -- 2.40.0