From: Aki Tuomi <cmouse@cmouse.fi>
Date: Thu, 21 May 2015 20:22:08 +0000 (+0300)
Subject: Update documentation about GSS-TSIG feature
X-Git-Tag: dnsdist-1.0.0-alpha1~248^2~79^2~9^2~7
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=b121d05f664a6e785df3526156cb354d0e992696;p=thirdparty%2Fpdns.git

Update documentation about GSS-TSIG feature
---

diff --git a/docs/markdown/authoritative/dnsupdate.md b/docs/markdown/authoritative/dnsupdate.md
index 6f6cfd9593..017f8c2642 100644
--- a/docs/markdown/authoritative/dnsupdate.md
+++ b/docs/markdown/authoritative/dnsupdate.md
@@ -47,7 +47,7 @@ sql> insert into domainmetadata(domain_id, kind, content) values(5, ‘ALLOW-DNS
 This will allow 198.51.100.0/8 and 203.0.113.2/32 to send DNS update messages for the example.org domain.
 
 ## TSIG-ALLOW-DNSUPDATE
-This setting allows you to set the TSIG key required to do an DNS update. An example:
+This setting allows you to set the TSIG key required to do an DNS update. If you have GSS-TSIG enabled, you can use Kerberos principals here. An example:
 
 ```
 sql> insert into tsigkeys (name, algorithm, secret) values ('test', 'hmac-md5', 'kp4/24gyYsEzbuTVJRUMoqGFmN3LYgVDzJ/3oRSP7ys=');
diff --git a/docs/markdown/authoritative/domainmetadata.md b/docs/markdown/authoritative/domainmetadata.md
index b001e3993e..409b8f7a98 100644
--- a/docs/markdown/authoritative/domainmetadata.md
+++ b/docs/markdown/authoritative/domainmetadata.md
@@ -29,6 +29,12 @@ When notifying this domain, also notify this nameserver (can occur multiple time
 ## AXFR-MASTER-TSIG
 Use this named TSIG key to retrieve this zone from its master (see [Provisioning signed notification and AXFR requests](modes-of-operation.md#provisioning-signed-notification-and-axfr-requests)).
 
+## GSS-ALLOW-AXFR-PRINCIPAL
+Allow this GSS principal to perform AXFR retrieval. Most commonly it is host/something@REALM, DNS/something@REALM or user@REALM. (See [GSS-TSIG support](gss-tsig.md)).
+
+## GSS-ACCEPTOR-PRINCIPAL
+Use this principal for accepting GSS context. (See [GSS-TSIG support](gss-tsig.md)).
+
 ## LUA-AXFR-SCRIPT
 Script to be used to edit incoming AXFRs, see [Modifying a slave zone using a script](modes-of-operation.md#modifying-a-slave-zone-using-a-script).
 
@@ -57,3 +63,6 @@ Available modes are:
 
 ## TSIG-ALLOW-AXFR
 Allow these named TSIG keys to AXFR this zone (see [Provisioning outbound AXFR access](modes-of-operation.md#provisioning-outbound-axfr-access)).
+
+## TSIG-ALLOW-DNSUPDATE
+This setting allows you to set the TSIG key required to do an DNS update. If GSS-TSIG is enabled, you can put kerberos principals here as well.
diff --git a/docs/markdown/authoritative/gss-tsig.md b/docs/markdown/authoritative/gss-tsig.md
new file mode 100644
index 0000000000..727ad55652
--- /dev/null
+++ b/docs/markdown/authoritative/gss-tsig.md
@@ -0,0 +1,15 @@
+# GSS-TSIG support
+
+GSS-TSIG allows authentication and authorization of DNS updates or AXFR using Kerberos with TSIG signatures. NB! This feature is *experimental* and subject to change on future releases.
+
+## Prerequisites
+
+-   Working Kerberos environment. Please refer to your Kerberos vendor documentation on how to setup it.
+-   Principal (such as DNS/<your.dns.server.name>@REALM) in either per-user keytab or system keytab.
+
+In particular, if something does not work, read logs and ensure that your kerberos environment is ok before filing an issue. Most common problems are time synchronization or changes done to the principal.
+
+## Setting up
+
+To allow AXFR / DNS update to work, you need to configure GSS-ACCEPTOR-PRINCIPAL in domain metadata. This will define the principal that is used to accept any GSS context requests. This *must* match to your keytab. Next
+you need to define one or more GSS-ALLOW-AXFR-PRINCIPAL entries for AXFR, or TSIG-ALLOW-DNSUPDATE entries for DNS update. These must be set to the exact initiator principal names you intend to use. No wildcards accepted.
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index 741a306dc3..7726ba634c 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -21,6 +21,7 @@ pages:
   - [authoritative/modes-of-operation.md, 'Authoritative', 'Modes of Operation']
   - [authoritative/domainmetadata.md, 'Authoritative', 'Domain metadata']
   - [authoritative/dnsupdate.md, 'Authoritative', 'Dynamic DNS Update']
+  - [authoritative/gss-tsig.md, 'Authoritative', 'GSS-TSIG']
   - [authoritative/internals.md, 'Authoritative', 'Internals']
   - [authoritative/virtual.md, 'Authoritative', 'Virtual Hosting']
   - [authoritative/performance.md, 'Authoritative', 'Performance Tuning and Monitoring']