From 2907164cc12444a03d8145b5bbf1be2314953e96 Mon Sep 17 00:00:00 2001
From: George <zhoreeq@users.noreply.github.com>
Date: Mon, 27 Jan 2020 07:14:08 -0500
Subject: [PATCH] Update docs

---
 README.md              | 18 +++++++++++
 USAGE.md               | 69 ++++++++++++++++++++++++++++++++++++++++++
 dnsmasq.conf           |  5 ---
 example.meshnamed.conf | 16 ----------
 4 files changed, 87 insertions(+), 21 deletions(-)
 create mode 100644 USAGE.md
 delete mode 100644 dnsmasq.conf
 delete mode 100644 example.meshnamed.conf

diff --git a/README.md b/README.md
index c4031c6..f1fc13b 100644
--- a/README.md
+++ b/README.md
@@ -46,6 +46,24 @@ for that zone.
 "xxx.mesh.arpa" name is itself managed by the DNS server derived from "xxx" and 
 can point to any other IPv6 address.
 
+## Resolving process explained
+
+1) A client application makes a request to a resolver.
+I.e. request AAAA record for "test.aiag7sesed2aaxgcgbnevruwpy.mesh.arpa.".
+
+2) When a resolver detects "mesh.arpa." domain, it extracts a third level 
+domain from it. In this example, "aiag7sesed2aaxgcgbnevruwpy.mesh.arpa.".
+
+3) If the resolver is configured as an authoritative server for that 
+domain, it sends back a response as a regular DNS server would do.
+
+4) If it's not, the resolver derives IPv6 address of the corresponding 
+authoritative DNS server from the third level domain.
+For "aiag7sesed2aaxgcgbnevruwpy.mesh.arpa." the authoritative server is 
+"200:6fc8:9220:f400:5cc2:305a:4ac6:967e".
+The resolver then relays clients request to a derived server address and 
+relays a response back to the client.
+
 ## Why not .ip6.arpa
 
 There is a special domain for reverse DNS lookups, but it takes 72 characters to
diff --git a/USAGE.md b/USAGE.md
new file mode 100644
index 0000000..6f973ff
--- /dev/null
+++ b/USAGE.md
@@ -0,0 +1,69 @@
+# meshnamed manual
+
+Minimum go version 1.12 is required.
+
+1) Get the source code and compile
+
+    git clone https://github.com/zhoreeq/meshname.git
+    cd meshname
+    make
+
+2) Generate the default config for your host
+
+    ./meshnamed genconf 200:6fc8:9220:f400:5cc2:305a:4ac6:967e | tee /tmp/meshnamed.conf
+
+3) Optionally, set the configuration with environment variables
+
+    export LISTEN_ADDR=[::1]:53535
+    export MESH_SUBNET=200::/7
+
+4) Run the daemon
+
+    ./meshnamed daemon /tmp/meshnamed.conf
+
+Add new DNS records to configuration file and restart the daemon to apply settings.
+A record can be of any valid string form parsed by [miekg/dns](https://godoc.org/github.com/miekg/dns#NewRR).
+
+## systemd unit
+
+Look for `meshnamed.service` in the source directory for a systemd unit file.
+
+## Example configuration file
+
+In this example, meshnamed is configured as authoritative for two domain zones:
+
+    {
+            "Domain":"aiag7sesed2aaxgcgbnevruwpy",
+            "Records": [
+                    "aiag7sesed2aaxgcgbnevruwpy.mesh.arpa. AAAA 200:6fc8:9220:f400:5cc2:305a:4ac6:967e",
+                    "_xmpp-client._tcp.aiag7sesed2aaxgcgbnevruwpy.mesh.arpa. SRV 5 0 5222 xmpp.aiag7sesed2aaxgcgbnevruwpy.mesh.arpa",
+                    "_xmpp-server._tcp.aiag7sesed2aaxgcgbnevruwpy.mesh.arpa. SRV 5 0 5269 xmpp.aiag7sesed2aaxgcgbnevruwpy.mesh.arpa",
+                    "xmpp.aiag7sesed2aaxgcgbnevruwpy.mesh.arpa. AAAA 300:6fc8:9220:f400::1",
+                    "forum.aiag7sesed2aaxgcgbnevruwpy.mesh.arpa. CNAME amag7sesed2aaaaaaaaaaaaaau.mesh.arpa."
+            ]
+    }
+    {
+            "Domain":"amag7sesed2aaaaaaaaaaaaaau",
+            "Records":[
+                    "amag7sesed2aaaaaaaaaaaaaau.mesh.arpa. AAAA 300:6fc8:9220:f400::5"
+            ]
+    }
+
+## Configure dnsmasq as a primary DNS resolver with "mesh.arpa." support
+
+`/etc/dnsmasq.conf`
+
+    port=53
+    domain-needed
+    bogus-priv
+    server=/mesh.arpa/::1#53535
+    server=8.8.8.8
+
+## Using meshnamed as a standalone DNS server
+
+Set environment varialbe to listen on all interfaces and a standard DNS server port
+
+    export LISTEN_ADDR=[::]:53
+
+Allow incoming connections to port 53/UDP in firewall settings.
+
diff --git a/dnsmasq.conf b/dnsmasq.conf
deleted file mode 100644
index 06f7fd4..0000000
--- a/dnsmasq.conf
+++ /dev/null
@@ -1,5 +0,0 @@
-port=53
-domain-needed
-bogus-priv
-server=/mesh.arpa/::1#53535
-server=8.8.8.8
diff --git a/example.meshnamed.conf b/example.meshnamed.conf
deleted file mode 100644
index c72866f..0000000
--- a/example.meshnamed.conf
+++ /dev/null
@@ -1,16 +0,0 @@
-{
-	"Domain":"aiag7sesed2aaxgcgbnevruwpy",
-	"Records": [
-		"aiag7sesed2aaxgcgbnevruwpy.mesh.arpa. AAAA 200:6fc8:9220:f400:5cc2:305a:4ac6:967e",
-		"_xmpp-client._tcp.aiag7sesed2aaxgcgbnevruwpy.mesh.arpa. SRV 5 0 5222 xmpp.aiag7sesed2aaxgcgbnevruwpy.mesh.arpa",
-		"_xmpp-server._tcp.aiag7sesed2aaxgcgbnevruwpy.mesh.arpa. SRV 5 0 5269 xmpp.aiag7sesed2aaxgcgbnevruwpy.mesh.arpa",
-		"xmpp.aiag7sesed2aaxgcgbnevruwpy.mesh.arpa. AAAA 300:6fc8:9220:f400::1",
-		"forum.aiag7sesed2aaxgcgbnevruwpy.mesh.arpa. CNAME amag7sesed2aaaaaaaaaaaaaau.mesh.arpa."
-	]
-}
-{
-        "Domain":"amag7sesed2aaaaaaaaaaaaaau",
-        "Records":[
-                "amag7sesed2aaaaaaaaaaaaaau.mesh.arpa. AAAA 300:6fc8:9220:f400::5"
-        ]
-}