From 5c09a910c7463737ee2d6db4d2c0d1b89d43132e Mon Sep 17 00:00:00 2001 From: George Date: Mon, 3 Feb 2020 12:23:58 -0500 Subject: [PATCH] Update README --- README.md | 120 +++++++++++++++++++++++----------------------------- USAGE.md | 69 ------------------------------ protocol.md | 83 ++++++++++++++++++++++++++++++++++++ 3 files changed, 136 insertions(+), 136 deletions(-) delete mode 100644 USAGE.md create mode 100644 protocol.md diff --git a/README.md b/README.md index 9175317..4d62109 100644 --- a/README.md +++ b/README.md @@ -1,83 +1,69 @@ # meshname -Special-use naming system for self-organized IPv6 mesh networks. +Minimum go version 1.12 is required. -## Motivation +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). -Having a naming system is a common requirement for deploying preexisting -decentralized applications. Protocols like e-mail, XMPP and ActivityPub require -domain names for server to server communications. +## systemd unit -Self-organized networks like CJDNS and Yggdrasil Network use public-key -cryptography for IP address allocation. Every network node owns -a globally unique IPv6 address. Binary form of that address can be encoded with -base32 notation for deriving a globally unique name space managed by that node. +Look for `meshnamed.service` in the source directory for a systemd unit file. -Since there is no need for a global authority or consensus, such a naming system -will reliably work in any network split scenarios. +## Example configuration file -".mesh.arpa" is meant to be used by machines, not by humans. A human-readable -naming system would require a lot more engineering effort. +In this example, meshnamed is configured as authoritative for two domain zones: -## How .mesh.arpa domains work + { + "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" + ] + } -Each mesh node can manage its own unique name space in "mesh.arpa." zone. -The name space is derived from its IPv6 address as follows: +## Configure dnsmasq as a primary DNS resolver with "mesh.arpa." support -1) IPv6 address is converted to its binary form of 16 bytes: +`/etc/dnsmasq.conf` - IPv6Address('200:6fc8:9220:f400:5cc2:305a:4ac6:967e') + port=53 + domain-needed + bogus-priv + server=/mesh.arpa/::1#53535 + server=8.8.8.8 - b'\x02\x00o\xc8\x92 \xf4\x00\\\xc20ZJ\xc6\x96~' +## Using meshnamed as a standalone DNS server -2) The binary value is encoded to base32: +Set environment varialbe to listen on all interfaces and a standard DNS server port - AIAG7SESED2AAXGCGBNEVRUWPY====== + export LISTEN_ADDR=[::]:53 -3) Padding symbols "======" are removed from the end of the string. +Allow incoming connections to port 53/UDP in firewall settings. -The resulting name space managed by '200:6fc8:9220:f400:5cc2:305a:4ac6:967e' -is "aiag7sesed2aaxgcgbnevruwpy.mesh.arpa." - -In order to resolve a domain in "xxx.mesh.arpa." space, the client derives IPv6 -address from the third level domain "xxx" and use it as authoritative DNS server -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 -store a single value. The same value in .mesh.arpa takes 36 characters. - -"e.7.6.9.6.c.a.4.a.5.0.3.2.c.c.5.0.0.4.f.0.2.2.9.8.c.f.6.0.0.2.0.ip6.arpa" -versus "aiag7sesed2aaxgcgbnevruwpy.mesh.arpa." - -This saves twice amount of bandwidth and storage space. It is also arguably more -aesthetically appealing, even though that's not a goal. - -## Why .arpa - -".arpa" is a special domain reserved for Internet infrastructure. There is a -similar special-use domain for home networks ".home.arpa" specified in RFC 8375. -If ".mesh.arpa" will become widely used it could also be standardized, otherwise -it won't break much. diff --git a/USAGE.md b/USAGE.md deleted file mode 100644 index e3de618..0000000 --- a/USAGE.md +++ /dev/null @@ -1,69 +0,0 @@ -# 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/protocol.md b/protocol.md new file mode 100644 index 0000000..9175317 --- /dev/null +++ b/protocol.md @@ -0,0 +1,83 @@ +# meshname + +Special-use naming system for self-organized IPv6 mesh networks. + +## Motivation + +Having a naming system is a common requirement for deploying preexisting +decentralized applications. Protocols like e-mail, XMPP and ActivityPub require +domain names for server to server communications. + +Self-organized networks like CJDNS and Yggdrasil Network use public-key +cryptography for IP address allocation. Every network node owns +a globally unique IPv6 address. Binary form of that address can be encoded with +base32 notation for deriving a globally unique name space managed by that node. + +Since there is no need for a global authority or consensus, such a naming system +will reliably work in any network split scenarios. + +".mesh.arpa" is meant to be used by machines, not by humans. A human-readable +naming system would require a lot more engineering effort. + +## How .mesh.arpa domains work + +Each mesh node can manage its own unique name space in "mesh.arpa." zone. +The name space is derived from its IPv6 address as follows: + +1) IPv6 address is converted to its binary form of 16 bytes: + + IPv6Address('200:6fc8:9220:f400:5cc2:305a:4ac6:967e') + + b'\x02\x00o\xc8\x92 \xf4\x00\\\xc20ZJ\xc6\x96~' + +2) The binary value is encoded to base32: + + AIAG7SESED2AAXGCGBNEVRUWPY====== + +3) Padding symbols "======" are removed from the end of the string. + +The resulting name space managed by '200:6fc8:9220:f400:5cc2:305a:4ac6:967e' +is "aiag7sesed2aaxgcgbnevruwpy.mesh.arpa." + +In order to resolve a domain in "xxx.mesh.arpa." space, the client derives IPv6 +address from the third level domain "xxx" and use it as authoritative DNS server +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 +store a single value. The same value in .mesh.arpa takes 36 characters. + +"e.7.6.9.6.c.a.4.a.5.0.3.2.c.c.5.0.0.4.f.0.2.2.9.8.c.f.6.0.0.2.0.ip6.arpa" +versus "aiag7sesed2aaxgcgbnevruwpy.mesh.arpa." + +This saves twice amount of bandwidth and storage space. It is also arguably more +aesthetically appealing, even though that's not a goal. + +## Why .arpa + +".arpa" is a special domain reserved for Internet infrastructure. There is a +similar special-use domain for home networks ".home.arpa" specified in RFC 8375. +If ".mesh.arpa" will become widely used it could also be standardized, otherwise +it won't break much.