Advanced Namespace Tools blog

02 January 2018

9front-ANTS live+install CD part 3: auth server setup

Many newcomers to Plan 9 are attracted by the promise of transparent network resource sharing and elegantly architected distributed systems. Experiencing those benefits as a new user has always been a challenge, because the installer has always configured a system as a single-user all in one terminal which does not run the services necessary to make and authenticate 9p network connections. Prior to the arrival of 9front, the process to move from a standalone terminal to a cpu/file server was documented on the Bell Labs wiki as Configuring a standalone CPU server and probably less than half of new users were able to follow this process without making a mistake somewhere, resulting in an endlessly varied series of error messages such as "auth server protocol botch" depending on exactly what you had screwed up:

9front has streamlined the process somewhat, and the 9front FQA offers a good walkthrough, but "I can't get drawterm/cpu to work" is still probably the most common configuration issue for newer users to navigate. I have always felt that it would be nice for the cd install procedure to help out with this, and provide an option to take the user through the process.

Required Steps

Getting fully operational auth services boils down to three tasks: setting a machine key in nvram, creating a password database for keyfs, and configuring /lib/ndb/local to know that the machine is an auth server. Making everything work right depends on coordinating the information in all these places: the machine key hostowner password needs to match that user's password in the keyfs database, and the machine key authentication domain needs to be in the network database and be understood to apply to the server. The errors people got usually be traced to failures to coordinate all this information successfully.

These errors were/are certainly the result of user mistakes - but the chances of making a mistake increase the longer and more elaborate a process is, and the more manual data editing is required. My goal in the installer was to provide a set of prompts and actions that would get the job done as quickly and efficiently as possible, and automate what could be automated. There are some drawbacks to this approach: autoconfiguration always requires some assumptions and users are good at violating assumptions, and learning to administer the system is an important skill. Many users' first exposure to important Plan 9 system files and concepts came about as a result of needing to work with their /lib/ndb/local and /rc/bin/cpurc. It is not a desirable goal to make users more ignorant, and the reason the standard 9front installer doesn't provide this service is the devs would prefer not to take that risk. Plan 9 is not an OS for people unwilling or unable to grapple with their own configuration and administration issues, so I hope users who find the ANTS installer convenient will still take the time to learn how all the pieces fit together.

Pwsetup and Ndbsetup

The new pwsetup script already existed, which setup the simplest possible form of remote access - hostowner only use with just a key in factotum. Another prompt was added to find out if the user wanted a full cpu/auth server, which would boot into no-gui console mode. If the user says yes to that prompt (it defaults to no) these steps are taken:

echo 'Enter hostowner password info for glenda nvram machine key.'
echo 'You will need to use this same password for the keyfs.'
echo 'auth/wrkey'
auth/factotum -S
echo 'Enter the same password you just gave for the keyfs database.'
echo 'auth/changeuser'
auth/keyfs /n/newfs/adm/keys
auth/changeuser glenda
factkey=`{cat /mnt/factotum/ctl |grep dp9ik}
ndbauthdom=`{echo $factkey(4) |sed 's/dom/authdom/'}
export ndbauthdom

The auth/factotum -S statement starts a cpu-server style factotum, which tries to read the machine key from nvram, fails, and then performs auth/wrkey, which is implemented by libauthsrv/readnvram. I also made a patch to readnvram.c to double-prompt for the key information to avoid possible typos that can happen when the information is only entered once. The next step is starting keyfs attached to the /adm/keys file of the newly created filesystem, and performing auth/changeuser for glenda.

The factotum now has the user's key, and this allows for the rest of the configuration to be done mostly automatically and with less possiblity of error, because the authdom is listed within the key and extracted into a tuple suitable for use with ndb. The ndbsetup script sets things up as follows:

if(~ $authservice yes){
	if(~ $ipaddr xxx){
		echo 'The ip address of this system should appear in the middle of this list:'
		cat /net/ipselftab
		prompt 'Enter ip address for auth services'
	if not
cp /n/newfs/lib/ndb/local /tmp/ndb.local
	ssam 'x/^.*ether='^$etheraddr^'.*$/ d' /tmp/ndb.local
	se = ('sys='^$sysname 'ether='^$etheraddr)
	case dhcp
		echo $se
		if(~ $authservice yes)
			echo '	ip='^$authip ' '$ndbauthdom ' auth='^$sysname
	case manual
		echo $se 'ip='^$ipaddr 'ipmask='^$ipmask 'ipgw='^$gwaddr
		if(~ $authservice yes)
			echo '	'^$ndbauthdom ' auth='^$sysname
		if(! ~ $#DNSSERVER 0){
			echo '	'	'dns='^$DNSSERVER
} >/n/newfs/lib/ndb/local

If the user specified manual configuration they will have entered their own ip address. If not, the system prints out the current ipselftab to have the user enter the current machine ip, which will appear in the list. The ipaddress, authdom from the factotum key, and previously entered system name are all then written into the ndb configuration. The fragile aspect of this is the assumption that the system ip will remain the same, even if DHCP configuration is chosen. I'm not sure if there is a way to avoid this. If the system ip address is unstable, the ndb mechanism will be problematic for auth services in general, and even when using DHCP, most systems retain the same ip over time.