ref: 2b9c1bd4a5980eb8dbff669f5cbef6a8e47dd69c
parent: ba1d7b8b5be56a039dc2eb9776f90ad70636467b
author: Moody <j4kem00dy@gmail.com>
date: Thu Nov 19 14:43:12 EST 2020
First draft of ndb-intro
--- /dev/null
+++ b/ndb-intro.md
@@ -1,0 +1,70 @@
+NDB: A brief introduction
+===
+
+NDB is one of the most crucial parts of configuring a set of networked plan9 machines.
+NDB serves as the central file for all network and service definitions in the system.
+
+The NDB configuration file itself is '/lib/ndb/local', a system of networked
+plan9 machines will typically have only one ndb file used(as they usually
+only have a single fs server). The file is organized as a series of 'key=value' entries
+per line, generally with one line per machine.
+
+A typical configuration for a terminal/fs hybrid laptop machine would be:
+
+ sys=laptop ether=00a0989e96e7 ip=
+
+This defines the sysname of the computer with the MAC address 00:a0:98:9e:96:e7. Without setting an ip and ipmask,
+this will instruct the system that the computer is meant to fetch these values from a DHCP server.
+
+For a static IP configuration we just need to add the ip and ipmask values to the line:
+
+ sys=laptop ether=00a0989e96e7 ip=192.168.1.6 ipmask=255.255.255.0 ipgw=192.168.1.1
+
+Setting this will allow tell the system to not only it's own IP if the MAC address matches, but can also
+be used to define what IP address is given out if plan9 is serving as your DHCP server. The ipgw key here
+tells the system to use that address(or sysname) as the default route.
+
+NDB also is used to define what other systems act as a service provider(fs, cpu, auth) as well as used to define
+what machines are part of which authdom. We set these properties like we do ip and ipmask, using 'key=value' entries
+where the value points to another system:
+
+ sys=terminal ether=00a0982bf765 ip=192.168.1.7 ipmask=255.255.255.0 ipgw=192.168.1.1 fs=kiri cpu=chiri auth=chiri authdom=ufo
+ sys=chiri ether=00a0986505c0 ip=192.168.1.8 ipmask=255.255.255.0 ipgw=192.168.1.1 fs=kiri cpu=chiri auth=chiri authdom=ufo
+ sys=kiri ether=00a09813037d ip=192.168.1.9 ipmask=255.255.255.0 ipgw=192.168.1.1 fs=kiri cpu=chiri auth=chiri authdom=ufo
+
+This defines a terminal, cpu/auth hybrid and fs server. The fs, cpu, and auth key values are set to the
+sysnames for machines that fill that role. The authdom is used to set the authentication domain that
+these machines belong to.
+
+As you can imagine, repeating these key tuples for each machine within a network
+can be a bit tedious, so NDB gives us the ability to define an ipnet:
+
+ # New lines with a tab are treated as part of the previous line
+ ipnet=space ip=192.168.1.0 ipmask=255.255.255.0
+ ipgw=192.168.1.1
+ dns=1.1.1.1
+ auth=chiri
+ authdom=ufo
+ fs=kiri
+ cpu=chiri
+
+This defines the ipnet 'space' which acts for the network 192.168.1.0/24. We can define shared
+tuples here that will be applied to machines that have an ip set within the network. Using this ipnet
+we can redo our previous machine configuration like so:
+
+ sys=terminal ether=00a0982bf765 ip=192.168.1.7 ipmask=255.255.255.0
+ sys=chiri ether=00a0986505c0 ip=192.168.1.8 ipmask=255.255.255.0
+ sys=kiri ether=00a09813037d ip=192.168.1.9 ipmask=255.255.255.0
+
+As mentioned a bit, NDB is not only used for setting networking settings but is also the file
+used by the plan9 DHCP and DNS servers to lookup entries. A DHCP request from MAC address
+'00:a0:98:2b:f7:65' will cause the DHCP server to look it up in the NDB file and will reply with its
+configured address '192.168.1.7'.
+
+For DNS some additional configuration is needed:
+
+ dom=local soa= ns=chiri
+ sys=kiri ether=00a09813037d ip=192.168.1.9 ipmask=255.255.255.0 dom=kiri.local
+
+This will set 'chiri' as the authorative DNS server for the domain '*.local' and define kiri with a
+domain name of 'kiri.local'.