Network Configuration
D1611428287
Aglenda
#The first section of this page describes the simplest possible setup
#for a standalone terminal, the rest of the page describes how to
#setup more complex Plan 9 network.
#
#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 (note: ping may not work in qemu, you may want to try hget
#instead). 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!service
#and 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!17008
#cs 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!service
#looks 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!17008
#i 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 |
#http://plan9.bell-labs.com/sys/doc/net.html] ( /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
#
|
