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
This commit is contained in:
Jan Dittberner 2015-11-07 22:17:43 +01:00
parent c058cc7b1d
commit 337947f50c
4 changed files with 307 additions and 78 deletions

View file

@ -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

View file

@ -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

View file

@ -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

View file

@ -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)