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 # The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes. # 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 # 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 # further. For a list of options available for each theme, see the

View file

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