From 655c658adf17bd7bc82818283803009ee0b0352c Mon Sep 17 00:00:00 2001
From: Alex Auvolat <alex@adnab.me>
Date: Wed, 7 Dec 2022 16:35:03 +0100
Subject: [PATCH] Add README

---
 README.md | 67 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..dcf6ed9
--- /dev/null
+++ b/README.md
@@ -0,0 +1,67 @@
+D53
+===
+
+[![Build Status](https://drone.deuxfleurs.fr/api/badges/lx/D53/status.svg)](https://drone.deuxfleurs.fr/lx/D53)
+
+D53 is a dynamic DNS updater that sources information from Consul to route services to the correct place
+
+### Tag syntax
+
+D53 reads tags affected to services in Consul. Tags can be formatted as follows:
+
+- `d53-a <domain> <subdomain>`, will set the node running this service as an IPv4 target in an A record for `<subdomain>.<domain>`
+- `d53-aaaa <domain> <subdomain>`, same but as an IPv6 target in a AAAA record
+- `d53-cname <domain> <subdomain>`, same but as an alias using a CNAME record
+
+Example Nomad service configurations:
+
+```hcl
+# The following can be used in the Tricot service definition
+# to redirect the current deuxfleurs.fr and <site_name>.site.deuxfleurs.fr
+# to this node through A and AAAA records
+    tags = [
+           "(diplonat (tcp_port 80))"
+           "d53-a deuxfleurs.fr ${meta.site}.site",
+           "d53-a deuxfleurs.fr global.site",
+           "d53-aaaa deuxfleurs.fr ${meta.site}.site",
+           "d53-aaaa deuxfleurs.fr global.site",
+         ]
+```
+
+```hcl
+# The following can be used in the Guichet service definition
+# to configure a Tricot reverse proxy entry, and to redirect using
+# a CNAME the guichet.deuxfleurs.fr to the correct target,
+# which is usually defined in the form of <site_name>.site.deuxfleurs.fr
+    tags = [
+           "tricot guichet.deuxfleurs.fr",
+           "d53-cname deuxfleurs.fr guichet",
+         ]
+```
+
+### Finding targets
+
+The IPv4, IPv6 and CNAME targets to set in the record are extracted from the metadata values affected to each node in the Consul configuration.
+In particular, the following values are used:
+
+- `public_ipv4`: a public IPv4 through which the current node is possibly reachable (see DiploNAT to automatically open ports in a NAT)
+- `public_ipv6`: a public IPv6 through which the current node is reachable
+- `cname_target`: a CNAME target that resolves to a domain name whose A and/or AAAA entries point to this node (possibly among others)
+
+Here is the relevant Nix configuration snippet that sets up these metadata values:
+
+```nix
+    let node_meta = {
+        "site" = cfg.site_name;
+        "public_ipv6" = cfg.ipv6;
+      } //
+      (if cfg.public_ipv4 != null
+        then { "public_ipv4" = cfg.public_ipv4; }
+        else {}) //
+      (if cfg.cname_target != null
+        then { "cname_target" = cfg.cname_target; }
+        else {});
+
+    ### ... later ...
+    services.consul.extraConfig.node_meta = node_meta;
+```