Update documentation

This commit adds documentation how to setup PowerDNS to use the
gnuviechadmin DNS schema. The queries are provided in a PowerDNS
configuration file.

Addresses #17

docs/conf.py

@@ -104,7 +104,7 @@ pygments_style = 'sphinx'
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
+html_theme = 'alabaster'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

docs/install.rst

@@ -43,3 +43,17 @@ In development::
 For production::
 
     $ pip install -r requirements.txt
+
+PowerDNS setup
+==============
+
+The models in :py:mod:`domains.models` are meant to be used together with a
+PowerDNS setup with the generic PostgreSQL backend
+(https://doc.powerdns.com/md/authoritative/backend-generic-mypgsql/). The
+database schema differs a bit from the original schema to fit the Django model
+conventions. To make PowerDNS work you have to redefine the SQL statements by
+copying the following content to
+:file:`/etc/powerdns/pdns.d/pdns.local.gva_queries.conf`.
+
+.. literalinclude:: pdns.local.gva_queries.conf
+   :language: properties

docs/pdns.local.gva_queries.conf

@@ -0,0 +1,198 @@
+# Regular queries
+gpgsql-basic-query=SELECT content, ttl, prio, type, domain_id, disabled::int, name, auth::int \
+    FROM domains_dnsrecord \
+    WHERE disabled=false AND type='%s' AND name=E'%s'
+gpgsql-id-query=SELECT content, ttl, prio, type, domain_id, disabled::int, name, auth::int \
+    FROM domains_dnsrecord \
+    WHERE disabled=false AND type='%s' AND name=E'%s' AND domain_id=%d
+gpgsql-any-query=SELECT content, ttl, prio, type, domain_id, disabled::int, name, auth::int \
+    FROM domains_dnsrecord \
+    WHERE disabled=false AND name=E'%s'
+gpgsql-any-id-query=SELECT content, ttl, prio, type, domain_id, disabled::int, name, auth::int \
+    FROM domains_dnsrecord \
+    WHERE disabled=false AND name=E'%s' AND domain_id=%d
+gpgsql-list-query=SELECT content, ttl, prio, type, domain_id, disabled::int, name, auth::int \
+    FROM domains_dnsrecord \
+    WHERE (disabled=false OR %d::bool) AND domain_id='%d' \
+    ORDER BY name, type
+
+# Master/slave queries
+gpgsql-master-zone-query=SELECT master \
+    FROM domains_dnsdomain \
+    WHERE domain=E'%s' AND type='SLAVE'
+gpgsql-info-zone-query=SELECT id, domain, master, last_check, notified_serial, type \
+    FROM domains_dnsdomain \
+    WHERE domain=E'%s'
+gpgsql-info-all-slaves-query=SELECT id, domain, master, last_check, type \
+    FROM domains_dnsdomain \
+    WHERE type='SLAVE'
+gpgsql-supermaster-query=SELECT customer \
+    FROM domains_dnssupermaster \
+    WHERE ip='%s' AND nameserver=E'%s'
+gpgsql-insert-slave-query=INSERT INTO domains_dnsdomain \
+    (type, domain, master, account) \
+    VALUES ('SLAVE', E'%s', E'%s', E'%s')
+gpgsql-insert-record-query=INSERT INTO domains_dnsrecord \
+    (content, ttl, prio, type, domain_id, disabled, name, auth) \
+    VALUES (E'%s', %d, %d, '%s', %d, %d::bool, E'%s', '%d')
+gpgsql-update-serial-query=UPDATE domains_dnsdomain \
+    SET notified_serial=%d \
+    WHERE id=%d
+gpgsql-update-lastcheck-query=UPDATE domains_dnsdomain \
+    SET last_check=%d \
+    WHERE id=%d
+gpgsql-info-all-master-query=SELECT id, domain, master, last_check, notified_serial, type \
+    FROM domains_dnsdomain \
+    WHERE type='MASTER'
+gpgsql-delete-zone-query=DELETE FROM domains_dnsrecord \
+    WHERE domain_id=%d
+
+# Comment queries
+gpgsql-list-comments-query=SELECT domain_id, name, type, modified_at, customer, comment \
+    FROM domains_dnscomment \
+    WHERE domain_id=%d
+gpgsql-insert-comment-query=INSERT INTO domains_dnscomment \
+    (domain_id, name, type, modified_at, customer, comment) \
+    VALUES (%d, E'%s', E'%s', %d, E'%s', E'%s')
+gpgsql-delete-comment-rrset-query=DELETE FROM domains_dnscomment \
+    WHERE domain_id=%d AND name=E'%s' AND type=E'%s'
+gpgsql-delete-comments-query=DELETE FROM domains_dnscomment \
+    WHERE domain_id=%d
+
+# Crypto key queries
+gpgsql-activate-domain-key-query=UPDATE domains_dnscryptokey \
+    SET active=true \
+    WHERE domain_id=( \
+        SELECT id \
+        FROM domains_dnsdomain \
+        WHERE domain=E'%s' \
+    ) AND domains_dnscryptokey.id=%d
+gpgsql-add-domain-key-query=INSERT INTO domains_dnscryptokey \
+    (domain_id, flags, active, content) \
+    SELECT id, %d, (%d = 1), '%s' FROM domains_dnsdomain \
+    WHERE domain=E'%s'
+gpgsql-clear-domain-all-keys-query=DELETE FROM domains_dnscryptokey \
+    WHERE domain_id=( \
+        SELECT id FROM domains_dnsdomain \
+        WHERE domain=E'%s' \
+    )
+gpgsql-deactivate-domain-key-query=UPDATE domains_dnscryptokey \
+    SET active=false \
+    WHERE domain_id=( \
+        SELECT id FROM domains_dnsdomain \
+        WHERE domain=E'%s' \
+    ) AND domains_dnscryptokey.id=%d
+gpgsql-list-domain-keys-query=SELECT domains_dnscryptokey.id, flags, CASE WHEN active THEN 1 ELSE 0 END AS active, content \
+    FROM domains_dnsdomain, domains_cryptokey \
+    WHERE domains_dnscryptokey.domain_id=domains_dnsdomain.id AND domain=E'%s'
+gpgsql-remove-domain-key-query=DELETE FROM domains_dnscryptokey \
+    WHERE domain_id=( \
+        SELECT id FROM domains_dnsdomain \
+        WHERE domain=E'%s' \
+    ) AND domains_dnscryptokey.id=%d
+
+# TSIG key queries
+gpgsql-delete-tsig-key-query=DELETE FROM domains_dnstsigkey \
+    WHERE name='%s'
+gpgsql-get-tsig-key-query=SELECT algorithm, secret \
+    FROM domains_dnstsigkey \
+    WHERE name=E'%s'
+gpgsql-get-tsig-keys-query=SELECT name, algorithm, secret \
+    FROM domains_dnstsigkey
+gpgsql-set-tsig-key-query=INSERT INTO domains_dnstsigkey \
+    (name, algorithm, secret) \
+    VALUES ('%s', '%s', '%s')
+
+# Metadata queries
+gpgsql-clear-domain-all-metadata-query=DELETE FROM domains_dnsdomainmetadata \
+    WHERE domain_id=( \
+        SELECT id FROM domains_dnsdomain \
+        WHERE domain=E'%s' \
+    )
+gpgsql-clear-domain-metadata-query=DELETE FROM domains_dnsdomainmetadata \
+    WHERE domain_id=( \
+        SELECT id FROM domains_dnsdomain \
+        WHERE domain=E'%s' \
+    ) AND domains_dnsdomainmetadata.kind=E'%s'
+gpgsql-get-all-domain-metadata-query=SELECT kind, content \
+    FROM domains_dnsdomain, domains_dnsdomainmetadata \
+    WHERE domains_dnsdomainmetadata.domain_id=domains_dnsdomain.id AND domain=E'%s'
+gpgsql-get-domain-metadata-query=SELECT content \
+    FROM domains_dnsdomain, domains_dnsdomainmetadata \
+    WHERE domains_dnsdomainmetadata.domain_id=domains_dnsdomain.id AND domain=E'%s' AND domains_dnsdomainmetadata.kind=E'%s'
+gpgsql-set-domain-metadata-query=INSERT INTO domains_dnsdomainmetadata \
+    (domain_id, kind, content) \
+    SELECT id, '%s', '%s' FROM domains_dnsdomain \
+    WHERE domain=E'%s'
+
+# Record queries
+gpgsql-delete-empty-non-terminal-query=DELETE FROM domains_dnsrecord \
+    WHERE domain_id='%d' AND name='%s' AND type IS NULL
+gpgsql-delete-names-query=DELETE FROM domains_dnsrecord \
+    WHERE domain_id=%d AND name=E'%s'
+gpgsql-delete-rrset-query=DELETE FROM domains_dnsrecord \
+    WHERE domain_id=%d AND name=E'%s' AND type=E'%s'
+gpgsql-get-order-after-query=SELECT ordername FROM domains_dnsrecord \
+    WHERE disabled=false AND ordername ~>~ E'%s' AND domain_id=%d AND ordername IS NOT NULL \
+    ORDER BY 1 USING ~<~ LIMIT 1
+gpgsql-get-order-before-query=SELECT ordername, name FROM domains_dnsrecord \
+    WHERE disabled=false AND ordername ~<=~ E'%s' AND domain_id=%d AND ordername IS NOT NULL \
+    ORDER BY 1 USING ~>~ LIMIT 1
+gpgsql-get-order-first-query=SELECT ordername, name FROM domains_dnsrecord \
+    WHERE disabled=false AND domain_id=%d AND ordername IS NOT NULL \
+    ORDER BY 1 USING ~<~ LIMIT 1
+gpgsql-get-order-last-query=SELECT ordername, name FROM domains_dnsrecord \
+    WHERE disabled=false AND ordername != '' AND domain_id=%d AND ordername IS NOT NULL \
+    ORDER BY 1 USING ~>~ LIMIT 1
+gpgsql-insert-empty-non-terminal-query=INSERT INTO domains_dnsrecord \
+    (domain_id, name, type, disabled, auth) \
+    VALUES ('%d', '%s', null, false, true)
+    gpgsql-insert-ent-order-query=INSERT INTO domains_dnsrecord \
+    (type, domain_id, disabled, name, ordername, auth) \
+    VALUES (null, '%d', false, E'%s', E'%s', '%d')
+gpgsql-insert-ent-query=INSERT INTO domains_dnsrecord \
+    (type, domain_id, disabled, name, auth) \
+    VALUES (null, '%d', false, E'%s', '%d')
+gpgsql-insert-record-order-query=INSERT INTO domains_dnsrecord \
+    (content, ttl, prio, type, domain_id, disabled, name, ordername, auth) \
+    VALUES (E'%s', %d, %d, '%s', %d, %d::bool, E'%s', E'%s', '%d')
+gpgsql-list-subzone-query=SELECT content, ttl, prio, type, domain_id, disabled::int, name, auth::int \
+    FROM domains_dnsrecord \
+    WHERE disabled=false AND (name=E'%s' OR name like E'%s') AND domain_id='%d'
+gpgsql-nullify-ordername-and-auth-query=UPDATE domains_dnsrecord \
+    SET ordername=NULL, auth=false \
+    WHERE name=E'%s' AND type=E'%s' AND domain_id='%d' AND disabled=false
+gpgsql-nullify-ordername-and-update-auth-query=UPDATE domains_dnsrecord \
+    SET ordername=NULL, auth=%d::bool \
+    WHERE domain_id='%d' AND name='%s' AND disabled=false
+gpgsql-remove-empty-non-terminals-from-zone-query=DELETE FROM domains_dnsrecord \
+    WHERE domain_id='%d' AND type IS NULL
+gpgsql-set-auth-on-ds-record-query=UPDATE domains_dnsrecord \
+    SET auth=true \
+    WHERE domain_id='%d' AND name='%s' AND type='DS' AND disabled=false
+gpgsql-set-order-and-auth-query=UPDATE domains_dnsrecord \
+    SET ordername=E'%s', auth=%d::bool \
+    WHERE name=E'%s' AND domain_id='%d' AND disabled=false
+gpgsql-zone-lastchange-query=SELECT MAX(change_date) FROM domains_dnsrecord \
+    WHERE domain_id=%d
+
+# Domain queries
+gpgsql-delete-domain-query=DELETE FROM domains_dnsdomain \
+    WHERE domain=E'%s'
+gpgsql-insert-zone-query=INSERT INTO domains_dnsdomain \
+    (type, domain) \
+    VALUES ('NATIVE', E'%s')
+gpgsql-update-kind-query=UPDATE domains_dnsdomain \
+    SET type='%s' \
+    WHERE domain='%s'
+gpgsql-update-master-query=UPDATE domains_dnsdomain \
+    SET master='%s' \
+    WHERE domain='%s'
+
+# Mixed queries
+gpgsql-get-all-domains-query=SELECT domains_dnsdomain.id, domains_dnsdomain.domain, domains_dnsrecord.content, \
+    domains_dnsdomain.type, domains_dnsdomain.master, domains_dnsdomain.notified_serial, domains_dnsdomain.last_check \
+    FROM domains_dnsdomain \
+    LEFT JOIN domains_dnsrecord \
+    ON domains_dnsrecord.domain_id=domains_dnsdomain.id AND domains_dnsrecord.type='SOA' AND domains_dnsrecord.name=domains_dnsdomain.domain \
+    WHERE domains_dnsrecord.disabled=false OR %d::bool

gnuviechadmin/domains/models.py

@@ -143,6 +143,8 @@ class DNSDomain(DomainBase):
     in the PowerDNS schema specified in
     https://doc.powerdns.com/md/authoritative/backend-generic-mypgsql/.
 
+    .. code-block:: sql
+
        CREATE TABLE domains (
          id                    SERIAL PRIMARY KEY,
          name                  VARCHAR(255) NOT NULL,
@@ -181,6 +183,8 @@ class DNSRecord(models.Model):
     table in the PowerDNS schema specified in
     https://doc.powerdns.com/md/authoritative/backend-generic-mypgsql/.
 
+    .. code-block:: sql
+
        CREATE TABLE records (
          id                    SERIAL PRIMARY KEY,
          domain_id             INT DEFAULT NULL,
@@ -238,6 +242,8 @@ class DNSSupermaster(models.Model):
     specified in
     https://doc.powerdns.com/md/authoritative/backend-generic-mypgsql/.
 
+    .. code-block:: sql
+
        CREATE TABLE supermasters (
          ip                    INET NOT NULL,
          nameserver            VARCHAR(255) NOT NULL,
@@ -272,6 +278,8 @@ class DNSComment(models.Model):
     comments table is used to store user comments related to individual DNS
     records.
 
+    .. code-block:: sql
+
        CREATE TABLE comments (
          id                    SERIAL PRIMARY KEY,
          domain_id             INT NOT NULL,
@@ -323,6 +331,8 @@ class DNSDomainMetadata(models.Model):
     The domainmetadata table is used to store domain meta data as described in
     https://doc.powerdns.com/md/authoritative/domainmetadata/.
 
+    .. code-block:: sql
+
        CREATE TABLE domainmetadata (
          id                    SERIAL PRIMARY KEY,
          domain_id             INT REFERENCES domains(id) ON DELETE CASCADE,
@@ -331,6 +341,7 @@ class DNSDomainMetadata(models.Model):
        );
 
        CREATE INDEX domainidmetaindex ON domainmetadata(domain_id);
+
     """
     domain = models.ForeignKey('DNSDomain')
     kind = models.CharField(max_length=32, choices=DNS_DOMAIN_METADATA_KINDS)
@@ -352,6 +363,8 @@ class DNSCryptoKey(models.Model):
     specified in
     https://doc.powerdns.com/md/authoritative/backend-generic-mypgsql/.
 
+    .. code-block:: sql
+
        CREATE TABLE cryptokeys (
          id                    SERIAL PRIMARY KEY,
          domain_id             INT REFERENCES domains(id) ON DELETE CASCADE,
@@ -361,6 +374,7 @@ class DNSCryptoKey(models.Model):
        );
 
        CREATE INDEX domainidindex ON cryptokeys(domain_id);
+
     """
     domain = models.ForeignKey('DNSDomain')
     flags = models.IntegerField()
@@ -382,6 +396,8 @@ class DNSTSIGKey(models.Model):
     This model represents the tsigkeys table in the PowerDNS schema specified
     in https://doc.powerdns.com/md/authoritative/backend-generic-mypgsql/.
 
+    .. code-block:: sql
+
        CREATE TABLE tsigkeys (
          id                    SERIAL PRIMARY KEY,
          name                  VARCHAR(255),
@@ -391,6 +407,7 @@ class DNSTSIGKey(models.Model):
        );
 
        CREATE UNIQUE INDEX namealgoindex ON tsigkeys(name, algorithm);
+
     """
     name = models.CharField(max_length=255)
     algorithm = models.CharField(max_length=50, choices=DNS_TSIG_KEY_ALGORITHMS)