shithub: docs.9front.org

ref: 198f12cf65a7f4730baf477972bdb94e5e7401fe
dir: /ndb-intro.md/

View raw version
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'.