--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/README	Mon Mar 19 13:56:47 2012 +0200
@@ -0,0 +1,81 @@
+Manage DNS/bind9 zonefiles.
+
+update:
+    ./bin/update reads data from settings/, and generates zonefiles under zones/.
+
+    `update` also shows and commits changes in settings/ data.
+
+bin/update-serial:
+    Increment DNS SOA record serials in the given .serial files.
+
+    Uses a YYYYMMDDXX format, but supports XX overflow.
+
+bin/process-zone:
+    Read zonefile containing records, and generate any of:
+
+    --check-hosts:
+        Check for duplicate host names/IPs.
+
+    --forward-zone:
+        Generate additional TXT/MX records to supplement A/CNAME records.
+
+    --reverse-zone=NET
+        Generate PTR records for all matching A records.
+
+    --meta-zone:
+        Generate additional TXT records from zonefile metadata, read from:
+
+            hg annotate -q --date | ./bin/process-zone --input-line-date ...
+
+bin/expand-zone:
+    Expand template vars in a zone textfile; does not parse records, just passes through lines.
+
+    Used to substitute e.g. `--serial .../foo.serial` values into SOA '{serial}' fields.
+
+bin/update:
+    Runs update-serial/process-zone/expand-zone to keep various generated zones/views up-to-date with respect to
+    source files under settings/
+
+    Also supports hg diff/commit/annotate integration with settings.
+
+settings/:
+    Input files, fed through update to generate files under zones/
+
+    *.serial:
+        Zone serial numbers for corresponding *.zone
+
+    *.zone:
+        Zone header, passed through process-zone with `--serial *.serial` and any appropriate `--expand view=...`.
+
+        May include a view-based $INCLUDE to include different zone data for different views.
+
+    *.zone.*:
+        Additional common zone data; copied to zones/, and $INCLUDE'd from *.zone.
+
+    *.txt:
+        Hosts zone data, used to generate forwards/reverse -hosts zones
+
+zones/:
+    Output files, loaded by bind.
+
+    *.zone:
+        View-independent zone headers with expanded serial.
+
+    *.zone.hosts:
+        View-independent generated zones for hosts.
+
+    *.zone.$view:
+        Per-view copied zone data.
+
+    *.zone.*:
+        Additional view-independent copied zone data.
+
+    $view/*.zone:
+        Per-view zone header with expanded $INCLUDE:s and serial.
+
+    $view/*.zone.hosts:
+        Per-view generated zones for hosts.
+
+    $view/*.zone -> .../$.zone:
+        Symlinked generic-zone data for some specific zone; either view-specific or view-independent.
+