From 337947f50c044500b1cfca230911e304cc7cef85 Mon Sep 17 00:00:00 2001
From: Jan Dittberner <jan@dittberner.info>
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)