From 337947f50c044500b1cfca230911e304cc7cef85 Mon Sep 17 00:00:00 2001 From: Jan Dittberner Date: Sat, 7 Nov 2015 22:17:43 +0100 Subject: [PATCH] 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 | 2 +- docs/install.rst | 14 +++ docs/pdns.local.gva_queries.conf | 198 +++++++++++++++++++++++++++++++ gnuviechadmin/domains/models.py | 171 ++++++++++++++------------ 4 files changed, 307 insertions(+), 78 deletions(-) create mode 100644 docs/pdns.local.gva_queries.conf diff --git a/docs/conf.py b/docs/conf.py index a1cec22..5fdf12e 100644 --- a/docs/conf.py +++ b/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 diff --git a/docs/install.rst b/docs/install.rst index 9e08482..2ac2b6e 100644 --- a/docs/install.rst +++ b/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 diff --git a/docs/pdns.local.gva_queries.conf b/docs/pdns.local.gva_queries.conf new file mode 100644 index 0000000..392b43b --- /dev/null +++ b/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 diff --git a/gnuviechadmin/domains/models.py b/gnuviechadmin/domains/models.py index ed6640a..405b2b5 100644 --- a/gnuviechadmin/domains/models.py +++ b/gnuviechadmin/domains/models.py @@ -143,18 +143,20 @@ class DNSDomain(DomainBase): in the PowerDNS schema specified in https://doc.powerdns.com/md/authoritative/backend-generic-mypgsql/. - CREATE TABLE domains ( - id SERIAL PRIMARY KEY, - name VARCHAR(255) NOT NULL, - master VARCHAR(128) DEFAULT NULL, - last_check INT DEFAULT NULL, - type VARCHAR(6) NOT NULL, - notified_serial INT DEFAULT NULL, - account VARCHAR(40) DEFAULT NULL, - CONSTRAINT c_lowercase_name CHECK (((name)::TEXT = LOWER((name)::TEXT))) - ); + .. code-block:: sql - CREATE UNIQUE INDEX name_index ON domains(name); + CREATE TABLE domains ( + id SERIAL PRIMARY KEY, + name VARCHAR(255) NOT NULL, + master VARCHAR(128) DEFAULT NULL, + last_check INT DEFAULT NULL, + type VARCHAR(6) NOT NULL, + notified_serial INT DEFAULT NULL, + account VARCHAR(40) DEFAULT NULL, + CONSTRAINT c_lowercase_name CHECK (((name)::TEXT = LOWER((name)::TEXT))) + ); + + CREATE UNIQUE INDEX name_index ON domains(name); """ # name is represented by domain @@ -181,28 +183,30 @@ class DNSRecord(models.Model): table in the PowerDNS schema specified in https://doc.powerdns.com/md/authoritative/backend-generic-mypgsql/. - CREATE TABLE records ( - id SERIAL PRIMARY KEY, - domain_id INT DEFAULT NULL, - name VARCHAR(255) DEFAULT NULL, - type VARCHAR(10) DEFAULT NULL, - content VARCHAR(65535) DEFAULT NULL, - ttl INT DEFAULT NULL, - prio INT DEFAULT NULL, - change_date INT DEFAULT NULL, - disabled BOOL DEFAULT 'f', - ordername VARCHAR(255), - auth BOOL DEFAULT 't', - CONSTRAINT domain_exists - FOREIGN KEY(domain_id) REFERENCES domains(id) - ON DELETE CASCADE, - CONSTRAINT c_lowercase_name CHECK (((name)::TEXT = LOWER((name)::TEXT))) - ); + .. code-block:: sql - CREATE INDEX rec_name_index ON records(name); - CREATE INDEX nametype_index ON records(name,type); - CREATE INDEX domain_id ON records(domain_id); - CREATE INDEX recordorder ON records (domain_id, ordername text_pattern_ops); + CREATE TABLE records ( + id SERIAL PRIMARY KEY, + domain_id INT DEFAULT NULL, + name VARCHAR(255) DEFAULT NULL, + type VARCHAR(10) DEFAULT NULL, + content VARCHAR(65535) DEFAULT NULL, + ttl INT DEFAULT NULL, + prio INT DEFAULT NULL, + change_date INT DEFAULT NULL, + disabled BOOL DEFAULT 'f', + ordername VARCHAR(255), + auth BOOL DEFAULT 't', + CONSTRAINT domain_exists + FOREIGN KEY(domain_id) REFERENCES domains(id) + ON DELETE CASCADE, + CONSTRAINT c_lowercase_name CHECK (((name)::TEXT = LOWER((name)::TEXT))) + ); + + CREATE INDEX rec_name_index ON records(name); + CREATE INDEX nametype_index ON records(name,type); + CREATE INDEX domain_id ON records(domain_id); + CREATE INDEX recordorder ON records (domain_id, ordername text_pattern_ops); """ domain = models.ForeignKey('DNSDomain') @@ -238,12 +242,14 @@ class DNSSupermaster(models.Model): specified in https://doc.powerdns.com/md/authoritative/backend-generic-mypgsql/. - CREATE TABLE supermasters ( - ip INET NOT NULL, - nameserver VARCHAR(255) NOT NULL, - account VARCHAR(40) NOT NULL, - PRIMARY KEY(ip, nameserver) - ); + .. code-block:: sql + + CREATE TABLE supermasters ( + ip INET NOT NULL, + nameserver VARCHAR(255) NOT NULL, + account VARCHAR(40) NOT NULL, + PRIMARY KEY(ip, nameserver) + ); """ ip = models.GenericIPAddressField() @@ -272,23 +278,25 @@ class DNSComment(models.Model): comments table is used to store user comments related to individual DNS records. - CREATE TABLE comments ( - id SERIAL PRIMARY KEY, - domain_id INT NOT NULL, - name VARCHAR(255) NOT NULL, - type VARCHAR(10) NOT NULL, - modified_at INT NOT NULL, - account VARCHAR(40) DEFAULT NULL, - comment VARCHAR(65535) NOT NULL, - CONSTRAINT domain_exists - FOREIGN KEY(domain_id) REFERENCES domains(id) - ON DELETE CASCADE, - CONSTRAINT c_lowercase_name CHECK (((name)::TEXT = LOWER((name)::TEXT))) - ); + .. code-block:: sql - CREATE INDEX comments_domain_id_idx ON comments (domain_id); - CREATE INDEX comments_name_type_idx ON comments (name, type); - CREATE INDEX comments_order_idx ON comments (domain_id, modified_at); + CREATE TABLE comments ( + id SERIAL PRIMARY KEY, + domain_id INT NOT NULL, + name VARCHAR(255) NOT NULL, + type VARCHAR(10) NOT NULL, + modified_at INT NOT NULL, + account VARCHAR(40) DEFAULT NULL, + comment VARCHAR(65535) NOT NULL, + CONSTRAINT domain_exists + FOREIGN KEY(domain_id) REFERENCES domains(id) + ON DELETE CASCADE, + CONSTRAINT c_lowercase_name CHECK (((name)::TEXT = LOWER((name)::TEXT))) + ); + + CREATE INDEX comments_domain_id_idx ON comments (domain_id); + CREATE INDEX comments_name_type_idx ON comments (name, type); + CREATE INDEX comments_order_idx ON comments (domain_id, modified_at); """ domain = models.ForeignKey('DNSDomain') @@ -323,14 +331,17 @@ class DNSDomainMetadata(models.Model): The domainmetadata table is used to store domain meta data as described in https://doc.powerdns.com/md/authoritative/domainmetadata/. - CREATE TABLE domainmetadata ( - id SERIAL PRIMARY KEY, - domain_id INT REFERENCES domains(id) ON DELETE CASCADE, - kind VARCHAR(32), - content TEXT - ); + .. code-block:: sql + + CREATE TABLE domainmetadata ( + id SERIAL PRIMARY KEY, + domain_id INT REFERENCES domains(id) ON DELETE CASCADE, + kind VARCHAR(32), + content TEXT + ); + + CREATE INDEX domainidmetaindex ON domainmetadata(domain_id); - CREATE INDEX domainidmetaindex ON domainmetadata(domain_id); """ domain = models.ForeignKey('DNSDomain') kind = models.CharField(max_length=32, choices=DNS_DOMAIN_METADATA_KINDS) @@ -352,15 +363,18 @@ class DNSCryptoKey(models.Model): specified in https://doc.powerdns.com/md/authoritative/backend-generic-mypgsql/. - CREATE TABLE cryptokeys ( - id SERIAL PRIMARY KEY, - domain_id INT REFERENCES domains(id) ON DELETE CASCADE, - flags INT NOT NULL, - active BOOL, - content TEXT - ); + .. code-block:: sql + + CREATE TABLE cryptokeys ( + id SERIAL PRIMARY KEY, + domain_id INT REFERENCES domains(id) ON DELETE CASCADE, + flags INT NOT NULL, + active BOOL, + content TEXT + ); + + CREATE INDEX domainidindex ON cryptokeys(domain_id); - CREATE INDEX domainidindex ON cryptokeys(domain_id); """ domain = models.ForeignKey('DNSDomain') flags = models.IntegerField() @@ -382,15 +396,18 @@ 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/. - CREATE TABLE tsigkeys ( - id SERIAL PRIMARY KEY, - name VARCHAR(255), - algorithm VARCHAR(50), - secret VARCHAR(255), - CONSTRAINT c_lowercase_name CHECK (((name)::TEXT = LOWER((name)::TEXT))) - ); + .. code-block:: sql + + CREATE TABLE tsigkeys ( + id SERIAL PRIMARY KEY, + name VARCHAR(255), + algorithm VARCHAR(50), + secret VARCHAR(255), + CONSTRAINT c_lowercase_name CHECK (((name)::TEXT = LOWER((name)::TEXT))) + ); + + CREATE UNIQUE INDEX namealgoindex ON tsigkeys(name, algorithm); - 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)