Network Configuration
-as of Thu Aug 9 07:49:09 EDT 2007-
STANDALONE TERMINAL NETWORK SETUP
To configure your network connection on a standalone terminal you only need to call ipconfig(8) and run ndb/dns -r.
If you have DHCP just run:
ip/ipconfig
Or to explicitly set the configuration:
ip/ipconfig -g <your-gateway> ether /net/ether0 <your-ip-address> <your-subnet-mask>
After calling ipconfig make sure to run ndb/dns -r to enable dns resolution.
To make this configuration permanent edit your /rc/bin/termrc commenting out and editing(if needed) the corresponding lines that call ipconfig(8).
You can use ip/ping to test that your network connection is working properly. If you have problems see the "troubleshooting" section below.
NETWORK DATABASE
Plan 9 uses a single database for storing all the network-related configuration information in the system.
The database stores the configuration for machines specifically identifiable by the local installation, default configurations for machines in particular subnets, domain name resolution information, and mappings between TCP service names and port numbers among other things.
The database is assembled from a number of text files bearing a particular record structure.
The default root of the database is the text file /lib/ndb/local. The most important entry in that file is the ``database='' entry, which specifies a list of other files to include. For example,
database= file=/lib/ndb/local file=/lib/ndb/local-cs file=/lib/ndb/common
It is from the contents of this file and those in the list that the database is assembled. These files are typically used by ndb/cs commands in the startup scripts(e.g. /rc/bin/cpurc).
Conventionally, the file /lib/ndb/common is for standard port definitions and the like; the other files hold actual system configuration.
RECORD STRUCTURE
Lexically, a record is an unindented line followed by a series of indented lines. Thus an unindented line, a blank line, or a comment line (one beginning with #) ends a record.
Semantically, a record is a series of ``key=value'' tuples. Tuples on the same line bind slightly more tightly than tuples on different lines, but usually that's not important.
An example record is:
ip=10.247.62.235 ip=10.247.60.200 sys=lusitania ether=0060088bc416 proto=il dom=lusitania.domain.dom
This record defines a system named ``lusitania'' with a specified ethernet address, two IP addresses, and a fully qualified domain name. The ``proto=il'' tuple indicates that the system speaks IL, the Plan 9 transport protocol of choice. By default, systems are assumed only to speak TCP.
Other useful attributes include:
auth default Plan 9 authentication server cpu default Plan 9 cpu server dns default DNS server (can be more than one) dnsdomain default DNS domain suffix (can be more than one) fs default Plan 9 file server ipgw IP gateway ipmask IP network mask ipsubmask IP subnetwork mask ntp default NTP server nntp default NNTP server smtp default SMTP server
IP HIERARCHY WALKING
Most information in the database is not stored in each system's record. Instead, the database query function ndbipinfo (see ndb(2)) and its simple command-line interface ndb/ipquery (see ndb(8)) understand about the hierarchy of IP networks.
When an attribute, say `fs', is needed for a system, the query routines start by looking up that system's network database record. If it has an fs= entry, ndbipinfo returns that value. Otherwise, ndbipinfo notes the system's IP address and walks down the IP hierarchy through the database, starting with the default IP network for the address.
Specifically, it starts with the default IP mask for the address, and'ing it with the IP address to find the default IP network. Suppose our address is 10.247.62.235, as above. The default IP mask for the address is 255.0.0.0, so the default IP network is 10.0.0.0.
Ndbipinfo looks for an ip=10.0.0.0 entry with an ipmask=255.0.0.0 entry. Suppose we find
ipnet=ten-net ip=10.0.0.0 ipmask=255.0.0.0 ipsubmask=255.255.255.0 smtp=mailserver.domain.dom ntp=ntpserver.domain.dom fs=myfs
The entry says that the network is composed of smaller subnetworks with mask 255.255.255.0, so we look for an entry for IP network 10.247.62.0 with the appropriate mask. Suppose we find (the value in the ipnet= tuple is irrelevant)
ipnet=my-net ip=10.247.62.0 ipmask=255.255.255.0 fs=my-other-fs ipgw=10.247.62.1
Since there's no ipsubmask entry, we stop the walk, returning ``my-other-fs'', as it is the fs= entry for the smallest subnet we found. Note that the my-net record entry trumps the ten-net record entry, just as an fs= entry in the lusitania record would trump both of them. If we hadn't found the fs= entry in my-net, we would have used the ten-net one.
The program ndb/ipquery (see ndb(8)) is good for testing that you have your network set up as you want, and that the IP hierarchy walks are happening as expected.
The default IP submasks are determined by the first number in the address:
0-127 255.0.0.0 128-191 255.255.0.0 192-223 255.255.255.0 224-239 These are reserved for multicast addresses 240-255 These are reserved for future use
(This is an internet standard, not a Plan 9 one.)
CONFIGURATION
Having read the preceding sections you can begin to define the layout of your network. An example configuration exists at /lib/ndb/local.complicated. A minimal configuration is presented here.
database= file=/lib/ndb/local file=/lib/ndb/common ipnet=mynetwork ip=192.168.0.0 ipmask=255.255.255.0 ipgw=192.168.0.1 dns=1.2.3.4 auth=mauretania ip=192.168.0.2 sys=mauretania ip=192.168.0.3 sys=aquitania
In this example we'll setup up the machine 'mauretania' as our first Plan 9 machine and make it the default authentication server for our 192.168.0.x subnet. We'll give our machine the IP address 192.168.0.2.
If you don't intend to have internet connectivity you may omit the ipgw and dns items.
IPCONFIG
Note that above we have defined two systems, one is 'mauretania', the other is called 'aquitania'. How does Plan 9 determine our machine is supposed to be 'mauretania'? The answer is ip/ipconfig.
When a Plan 9 machine boots, it runs the configuration script /rc/bin/termrc or /rc/bin/cpurc, depending on whether it is a terminal or a CPU server.
In /rc/bin/termrc you will find the line
ip/ipconfig >/dev/null >[2=1]
This line causes the machine to look for a DHCP server to supply it with configuration information. You can set up a Plan 9 CPU/authentication server to run a DHCP server. When you do this the server will look up it's network database and serve out the configuration defaults.
Nevertheless, there isn't yet enough information there to give a specific machine a fixed IP. One way of doing this is to bind a specific configuration to a specific network card's MAC address. Each physical network card is given an unique MAC address when manufactured. You can find out your card's MAC address by typing the line
cat /net/ether0/addr
(If there isn't a /net/ether0 directory then Plan 9 did not find an ethernet card on your system.) You can now add the MAC address as an attribute of the configuration line in the ndb like
ip=192.168.0.2 sys=mauretania ether=abc12345def
where 'abc12345def' is the MAC address. Of course if there isn't a Plan 9 DHCP server on the network, this method won't work. When setting up your first Plan 9 machine, you can modify the ip/ipconfig line to specify a specific gateway, ip, and ip-mask to use.
ip/ipconfig -g 192.168.0.1 ether /net/ether0 192.168.0.2 255.255.255.0
You now have enough information to follow the instructions for Configuring a Standalone CPU Server. It will guide you in setting up a system suitable as any combination of CPU server, Authentication server, DHCP server, and even a light-weight kfs (file) server. For a proper file server see Installing a Plan 9 file server.
TROUBLESHOOTING
If ipconfig gives an error of the form
ip/ipconfig: binding device: '/net/ether0' cs: file does not exist
it indicates that the kernel has not detected your network card. For a PC, make sure that your plan9.ini(8) file specifies the proper network driver. If that doesn't help, it could be that the proper network driver is not compiled into the kernel that you're using. See Compiling kernels for information on how to make a new kernel.
If after installing a fossil+venti system you get an error message like
ndb/dns: can't read my ip address
you might want to edit the /rc/bin/termrc to omit the test conditions for both ip/ipconfig and ndb/dns - the relevant section should just read something like:
ip/ipconfig >/dev/null >[2=1] ndb/dns -rf $NDBFILE
QUERY TOOLS
ndb/query and ndb/ipquery look directly in the ndb files. ndb/query does simple direct queries based on the given attribute and value, ndb/ipquery searches more extensively up through the subnet hierarchy. They are both good tools to check basic functioning of an ndb file. If they don't produce sensible results, it's unlikely cs will. ndb/query and (probably) ndb/ipquery do not talk to ndb/cs or ndb/dns at all.
ndb/csquery simply opens /net/cs and speaks its protocol, which expects strings of the form
net!host!serviceand replies with translations of them:
term% ndb/csquery > net!plan9.bell-labs.com!9fs /net/il/clone 204.178.31.2!17008!fasttimeout /net/tcp/clone 204.178.31.2!564 /net/il/clone 204.178.31.2!17008cs relies on dns to translate domain names to ip addresses. It does not expect a plain name such as `p9'. It translates dial(2) addresses.
There's a special case that's also useful in checking whether your host, subnet and net defaults for services are reasonable.
net!$attr!servicelooks for the given attribute `attr' through the subnet hierarchy starting at the host and working up. Thus the dial(2) string `net!$fs!9fs' dials the (default) file server configured for the current node, and the translation can be checked by:
term% ndb/csquery > net!$fs!9fs /net/il/clone 144.32.112.69!17008!fasttimeout /net/tcp/clone 144.32.112.69!564 /net/il/clone 144.32.112.69!17008i don't know without a lot of grepping how much the $attr is used now but it is used to find an authentication server in the absence of an authdom (see /sys/src/libauthsrv/authdial.c). It doesn't really matter because the point here is that $xyz can be used to check that cs gives a sensible value for xyz for the current node.
ndb/dnsquery opens /net/dns and uses its protocol:
ndb/dnsquery > bell-labs.com ns bell-labs.com ns ns.research.att.com bell-labs.com ns yeats.pa.bell-labs.com bell-labs.com ns crufty.research.bell-labs.com bell-labs.com ns ns1.research.bell-labs.com bell-labs.com ns dirty.research.bell-labs.com bell-labs.com ns ns2.research.bell-labs.com > plan9.bell-labs.com plan9.bell-labs.com ip 204.178.31.2
BOOTING VIA PXE
To boot a machine using PXE set add an entry to /lib/ndb/local something like:
sys=doris ether=03294ea93902 ip=192.168.0.32 dom=doris.mydomain.com bootf=/386/9pxeload authdom=mydomain.com
The intial boot via DHCP will discover the ether config and download 9pxeload. This will then pull down its plan9.ini file which it expects to find in the file:
/cfg/pxe/<mac address>.
bootstrap then continues as usual.
SEE ALSO
Dialup modem config, DNSMASQ, ipconfig(8), ndb(8), ndb(6), The Organization of Networks in Plan 9 ( /sys/doc/net/net.ps )
Todo:
BOOTSTRAPPING OTHER SYSTEMS
...
explain items in cpurc
ndb/cs ndb/dns ip/dhcp ip/tftp aux/timesync /net/ndb auth/keyfs aux/listen
