Add README.md with usage documentation

README.md

@@ -0,0 +1,72 @@
+# CAcert DNS zones
+
+CAcert runs its own public DNS nameservers on ns1 and ns2 in its BIT datacenter
+rack in Ede.
+
+We use [PowerDNS](https://doc.powerdns.com/authoritative/index.html) installed
+on Debian systems.
+
+This repository contains a Python script `update-zones.py` that is used for
+updating DNS information from this Git repository.
+
+The canonical URL for this repository is
+[https://code.cacert.org/critical/dns-zones.git](https://code.cacert.org/critical/dns-zones.git).
+
+## Prerequisites
+
+The server certificate for https://code.cacert.org/ needs to be trusted.
+Therefore the CAcert root CA certificate needs to be put into
+`/usr/local/share/ca-certificates` and hast to be registered as trusted by
+running
+
+```shell
+update-ca-certificates
+```
+
+The `update-zones.py` script needs `git`, `pdnsutil` and `python3`. We only use
+the Python 3 standard library and no external dependencies. The script uses
+`/usr/lib/sendmail` to send change mails. Mail sending has been tested with
+ssmtp and exim4.
+
+To make sure that all these prerequisites are met, you may run
+
+```shell
+apt install python3 ca-certificates pdns-server git mail-transport-agent
+```
+
+## Cloning the repository
+
+The git configuration on ns1 and ns2 has been adapted to allow remembering the
+credentials to clone the repository. A separate user pdnssync has been setup to
+allow cloning the repository.
+
+This repository is meant to be cloned on the CAcert DNS servers ns1 and ns2.
+
+```shell
+cd ~
+git config --global credential.helper store
+git config --global pull.ff only
+git clone https://code.cacert.org/critical/dns-zones.git
+```
+
+Credentials will only be asked for the initial clone. The credential helper
+records them in in `~/.git-credentials`.
+
+## Updating zones
+
+The user running the update needs read access to the configuration in
+`/etc/powerdns` (either member of the pdns group or root).
+
+```
+$ cd ~/dns-zones
+$ git pull
+$ ./update-zones.py
+```
+
+The `update-zones.py` tracks the local status in a branch (default
+'provisioned') that is updated when
+
+* a) zone changes have been applied
+* b) the running PowerDNS is responsible as secondary nameserver
+
+The `update-zones.py` script should be run on both nameservers.