Plan9

Plan9 is an operating system designed by developers at Bell Labs.

Although Plan 9 derives from Unix it uses a different approach, and is not compatible with Unix like Operating Systems.. Commands differ, the internal workings differ, setup, configuration and maintenance differ.

See the Homepage for lots of Talk about this.

About this Tutorial

This Tutorial walks through setup and configuration and maintenance tasks of a Network of Plan9 machines, taking into account the most recent kernels and tools (at the time of writing, of course).

A rather good understanding of computers and operating systems is required, you should at least know Linux or any other Unix like operating system from the point of view of a Systemadministrator.

I have put it together while figureing out things out for myself. The main source of information have been the excelent manual pages of Plan9 as well as the papers, all found on the Plan9 homepage.

There are two intended modes of reading:

Newcomers:

should be able to read and execute this tutorial from top to bottom and find themselves left with a working Plan9 network

Recidivists:

should find it easy to encounter the bits and pieces of information they always wanted to have in one place

While following the steps, one should be able to copy and paste the given examples (with shaded background) either directly to the target system, or, as I do often for the Xen/textonly installations, copy them to an open editor window of the host operating system, modify what needs to, and copy and paste from the editor window to the Plan9 console or terminal.

Since this is a Wiki, the whole tutorial is made up of single Wiki pages containing just the information of a certain context, and can be accessed directly. Find here the list of pages of the tutorial:

A Plan9 Network

in Plan9 (almost) any resource can be on another machine in the Network so, there are several roles a machine can take:

terminal:

Every end user is working with a terminal. A terminal machine has mouse, keyboard and a graphics display. It needs not have a hard disk, since files can be provided by a fileserver. The program drawterm simulates the behaviour of a terminal under other operating systems thus can be used as a terminal too.

fileserver:

the name is ambiguous, since a fileserver really is a program serving files either locally or via the network. As a machine, a "fileserver" runs a fileserver, thus providing its disk space, to other computers. Mainly: space for the user to store data as well as the program files the user is executing. There can be several "fileservers" in a network, and a user will surely use external fileservers like for example the Plan9 sources fileserver.

cpuserver:

programs can be executed either locally or on a cpuserver; also processortime is a shared resource to Plan9. There can be several cpuservers in a Plan9 Network.

authserver:

A Plan9 network is "hold together" by an authserver. This is a program which authenticates users of an authentication domain via the network. For security reasons it is recommendable to run the authserver on a dedicate machine, which would then be the "authserver". So in one Plan9 network there is just one authentication server. In practice the authentication domain will be a string the same as the DNS domain of the network, or a subdomain of it.

Kernel types

File, cpu and authentication server normally don't need a mouse, keyboard, and display, since they should be left alone and are probably locked away in a serverroom.

The Plan9 kernel can be (re)compiled to accomplish the different tasks described in "A Plan9 Network", as well as with the drivers needed for a certain hardware configuration. Thus the kernel size is kept small and more space for user processes is left.

There is a distinction between "cpu" and "terminal" kernels:

terminal:

at bootup a terminal kernel asks for a username. This user will be the hostowner until the next reboot. If any resource on the network which requires authorization is accessed, authentication against the user with the same name in the authserver is initiated.
It is often handy to have a terminal kernel around even on cpu machines for administrative and maintenance tasks, because you can become any user without being asked for a password.

cpu:

a cpu kernel reads the username (an password) of the hostowner either from nvram, or from a 1 block partition on the harddisk which is used to simulate the nvram. Thus the cpu kernel can startup without user interaction.

During the boot process an initial rc script is run. On a terminal kernel it is looked for at /rc/bin/termrc, on the cpu kernel in /rc/bin/cpurc

The goal of the tutorial is to set up a complete, usable scenario for a network of Plan9 machines, suitable as well for playing around, as for to kickstart a production environment.

For simplicity of the instructions, the hostowner on the cpu machines is left as "glenda", even on the cpu machines. A separate chapter .?/CpuChangeHostowner will/shall be written to show how to change the hostowner of the cpuservers.

• two machines will be set up: an authserver and a cpu & fileserver.
• all involved machines receive their IP number from an external dhcp server
• the domainnames of the involved machines are resolved by en external dns server
• the fileserver uses an external ntp server to syncronise its time, all other involved machines use the fileserver for time syncronization
• the authserver:
  • runs fossil without venti
  • secstored
• the fileserver:
  • runs fossil+venti

Os Installation

You will (obviously) have to install Plan9 on several computers. For this you have several choices:

• Install on a dedicated hardware: * See the official installation instructions
• Installation under Qemu
  • ./QemuInstall
• Installation under Xen
  • ./XenInstall After this you can proceed with the network setup.

If you are using Xen instances - which do not provide a grafical environment, you will want to connect to your Plan9 computers via drawterm which runs under Linux, OsX and Windows.

Setup of different Services

This instructions suppose that you just have set up a plain Plan9 computer. Remember that setup is done with a terminal kernel, an authserver however will run with a cpu kernel and startup autonomously with a predefined user as the hostowner.

An appropiate /rc/bin/cpurc file has to be crafted and installed. Also, of course, networking has to be set up correctly, since the purpose of the authserver is to provide authentication in the network. Our workflow will be more or less:

1. boot with a terminal kernel as user glenda (first hostowner ever)
2. install (and test) /lib/ndb/local
3. install /rc/bin/cpurc
4. assure that the authserver starts at bootup
5. configure the default hostowner
6. reboot into a cpu kernel
7. set up the hostowner secstore account
8. start using your authserver

network configuration

• cat >/lib/ndb/local <<EOF
  
  
  /lib/ndb/local
  
  

LEG16112006

#

main network database configuration file

files comprising the database

database= file=/lib/ndb/local file=/lib/ndb/common file=/lib/ndb/auth

ipnet=magma.intern ip=10.0.0.0 ipmask=255.255.255.0 dnsdomain=magma.intern dns=10.0.0.1 ntp=router smtp=router authdom=magma.intern auth=porticus cpu=schiefer fs=schiefer

what's my name:

ip=10.0.0.6 sys=porticus

localhost

ip=127.0.0.1 sys=localhost dom=localhost

auth=sources.cs.bell-labs.com authdom=outside.plan9.bell-labs.com EOF

cpurc

• cat > /rc/bin/cpurc <<EOF
  
  
  !/bin/rc
  
  

/rc/bin/cpurc

LEG16112006

#

cpurc for authserver

echo -n cpu > /env/service date > /env/boottime

replace FILESERVER with the name of your file server

here we start with kfs, your local disk file system

fileserver=kfs

default authdom

authdom=magma.intern

the local domain to be used in the faces database

facedom=magma.intern

mount points

mntgen -s slashn && chmod 666 /srv/slashn

configure ip address

ip/ipconfig

name translation, cs sets /dev/sysname

ndb/cs sysname=`{cat /dev/sysname} ndb/dns -r

extract info about our network from ndb

ndb/query ipnet $$authdom |rc

parallelism for mk

NPROC = `{wc -l </dev/sysstat}

we use the fileserver for syncing time

aux/timesync -f -l $fs

start the secstored

auth/secstored

authserver

auth/keyfs -wp -m /mnt/keys /adm/keys >/dev/null >[2=1] auth/cron >>/sys/log/cron >[2=1] &

services available to networks

aux/listen -q -t /rc/bin/service.auth -d /rc/bin/service il aux/listen -q -t /rc/bin/service.auth -d /rc/bin/service tcp EOF

authserver

• auth database

  cat >/lib/ndb/auth <<EOF
  
  
  /lib/ndb/auth
  
  

LEG16112006

#

auth database for authserver

hostid=porticus uid=!sys uid=!adm uid=*

EOF * enable listening on the auth port:

cd /rc/bin/service.auth
mv authsrv.il566 il566
mv authsrv.tcp567 tcp567

* Eventually disable dummy services

cd /rc/bin/service
mv il566 !il566
mv tcp567 !tcp567

hostowner

* to set up the default hostowner and her password run

auth/wrkey

* answer the following questions: authid:

glenda

authdom:

magma.intern

secstore key:

password with at least eight (8) characters, this is not the password for glenda, but the encryption key for the 'nvram' partition.

password:

password for glenda, must be the same /!\ as in the keyserver and also have at least eight characters

.

* give the hostowner accessrights to the keystores and user database files:

* connect to the fossil console

con /srv/fscons

fsys main

uname adm +glenda

* type 'Ctl+\' then 'q' to disconnect from the con

* start keyserver and create the entry for the hostowner:

auth/keyfs

auth/changeuser glenda

* answer the following questions: Password:

must be the same /!\ as above

Confirm:

must be the same /!\ as above (humhm.. are we getting tired yet?)

assign Inferno/POP secret?:

y

make it the same as the plan 9 password?:

y

Expiration date (YYYYMMMDD or never)[return = never]:

just hit return

Post id:

Glenda

Users's full name:

Hostowner of porticus

Department:

Systems

Users's email address:

glenda

Sponsor's email address:

admin@magma.intern

* this address receives copy of notifications when glenda's password is about to expire other email address:

.. don't ask, I sure don't know (yet?)

Reboot

Stop the filesystem safely with fshalt, then reboot with '^T^Tr', or 'Ctrl+Alt+Del'

You should be able to connect from a remote system to the authserver e.g. with drawterm:

drawterm -a porticus -c porticus -u glenda

Still remember the password of glenda???

You can also login at the console if you were using Xen

hostowners secstore account

The secstore is a secure and comfortable way to store passwords, host-keys etc. in a network environment. Each user may have a secstore, it will be queryied first when authenticating to some network service. The secstore most probably runs on the authserver, just as in our example. Now we add the secstore for the hostowner of the authserver to the secstore daemons files.

Run the command: auth/secuser glenda, it will ask:

glenda password:

this is not the plan9 user glenda's password, so choose another one

retype password:

?BR

expires [DDMMYYYY, default = 18112007]:

?BR

Enabled or Disabled [default Enabled]::: ?BR require STA? [default no]::: ?BR comments [default = ]::: ?BR

We pretty much leave everything with default values.

To store passwords in an easy way, we'll need a running terminal first.

Security

You may want to disallow remote cpu connections to the authserver. Services are scripts in either /bin/service or /bin/service.auth.

The following scripts in /bin/service contain "cpu", after disabling them I could no longer log in remotely with drawterm into my authserver.

• tcp17005
• tcp17006
• tcp17010
• tcp17013 To disable a service just rename it e.g. be putting a '!' in front of the name.

cd /bin/service
mv tcp17005 !tcp17005
mv tcp17006 !tcp17006
mv tcp17010 !tcp17010
mv tcp17013 !tcp17013

This instructions suppose that you just have set up a plain Plan9 computer with fossil+venti support. You do not want to run a fileserver without venti.

Remember that setup is done with a terminal kernel, a fileserver however will run with a cpu kernel and startup autonomously with a predefined user as the hostowner.

An appropiate /rc/bin/cpurc file has to be crafted and installed. Also, of course, networking has to be set up correctly, since the purpose of the fileserver is to provide access to its harddisk from the network. Our workflow will be more or less:

1. boot with a terminal kernel as user glenda (first hostowner ever)
2. install (and test) /lib/ndb/local
3. install /rc/bin/cpurc
4. configure the default hostowner
5. make the fossil fileserver listen to the network
6. reboot into a cpu kernel
7. start using your fileserver

network configuration

• cat >/lib/ndb/local <<EOF
  
  
  /lib/ndb/local
  
  

LEG17112006

#

main network database configuration file

files comprising the database

database= file=/lib/ndb/local file=/lib/ndb/common

ipnet=magma.intern ip=10.0.0.0 ipmask=255.255.255.0 dnsdomain=magma.intern dns=10.0.0.1 ntp=router smtp=router authdom=magma.intern auth=porticus cpu=schiefer fs=schiefer

what's my name:

ip=10.0.0.7 sys=schiefer

localhost

ip=127.0.0.1 sys=localhost dom=localhost

auth=sources.cs.bell-labs.com authdom=outside.plan9.bell-labs.com EOF

cpurc

• cat > /rc/bin/cpurc <<EOF
  
  
  !/bin/rc
  
  

/rc/bin/cpurc

LEG17112006

#

cpurc for fileserver

echo -n cpu > /env/service date > /env/boottime

replace FILESERVER with the name of your file server

here we start with kfs, your local disk file system

fileserver=kfs

default authdom

authdom=magma.intern

the local domain to be used in the faces database

facedom=magma.intern

mount points

mntgen -s slashn && chmod 666 /srv/slashn

configure ip address

ip/ipconfig

name translation, cs sets /dev/sysname

ndb/cs sysname=`{cat /dev/sysname} ndb/dns -r

extract info about our network from ndb

ndb/query ipnet $$authdom |rc

parallelism for mk

NPROC = `{wc -l </dev/sysstat}

The fileserver will also be timeserver with stratum 9

aux/timesync -n -l -S 9

services available to networks

aux/listen -q -t /rc/bin/service.auth -d /rc/bin/service il aux/listen -q -t /rc/bin/service.auth -d /rc/bin/service tcp EOF

hostowner

* to set up the default hostowner and her password run

auth/wrkey

* answer the following questions: authid:

glenda

authdom:

magma.intern

secstore key:

password with at least eight (8) characters, this is not the password for glenda, but the encryption key for the 'nvram' partition.

password:

password for glenda, must be the same /!\ as in the keyserver and also have at least eight characters

fileserver

• read the fileserver configuration file
• add the commands to make fossil listen on the network

• write the file back Notes:

• change /dev/sd00/fossil if your fossil is on another disk or partition

  cd
  fossil/conf /dev/sd00/fossil >flproto.bak
  cp flproto.bak flproto
  cat >> flproto <<EOF
  listen tcp!!564
  listen il!!17008
  EOF
  fossil/conf -w /dev/sd00/fossil flproto

Reboot and enjoy

Stop the filesystem safely with fshalt, then reboot with '^T^Tr', or 'Ctrl+Alt+Del'

Make sure to start now with a cpu/fileserver kernel (9pccpuf).

You should be able to connect from a remote system to the fileserver e.g. with drawterm:

drawterm -a porticus -c schiefer -u glenda

Connecting with a Terminal

• TODO: there are several forms how to get to a terminal, e.g. installing Plan9 under Qemu. However I'd like to facilitate a prefabricated Qemu-Term kernel and setup, which doesn't need the setup CD then. TODO: termrc and especially /lib/ndb/* setup for the terminal

Secstore

There are essentially two tasks to set up and fill a secstore for a user:

• creating the secstore user on the authserver with an "administrative" account
• creating a (factotum) file on the secstore as the secstore user The first step has already been done for the hostowner user of the authserver. We repeat the command here for reference, you must be logged in as the hostowner on the authserver:

auth/secuser <user>

You will be asked for the secstore password (which is not the user password) and some other data for which you can (should) use the defaults.

Now start a terminal as the user for which you created the secstore. Or tell the user to do this and proceed as follows. You need both: the secstore password and the users password.

• open a fresh window in the terminal
• log into the authserver to generate an entry in factotum

cpu -h porticus
exit

• create an initial factotum file and edit it

ramfs –p; cd /tmp
cat /mnt/factotum/ctl > factotum
acme factotum

• You get a line like: key proto=p9sk1 dom=magma.intern user=user!password?
• change the ? sign at the end of the line to =password, ok, make it look like:
  • key proto=p9sk1 dom=magma.intern user=user!password=password
• store the modified file to the secstore

auth/secstore –p factotum

• then destroy the window, to leave no traces of your cleartext password. When you login next time, you will be asked for your secstore password instead of your user password.

Maintenance of the factotum file is done by the ipso command, which must be run from a standalone terminal. We'll see into that later.

Administrative Tasks

To add a user the following steps have to be executed:

1. The user must be known to the fileserver (and have a home directory)?BR In order to (auto)create the user profile completely the user must be in the sys group
2. The user must be known to the authserver
3. Login for the first time and create a default profile

fileserver

• connect to the fileserver
• connect to the fossil console and add the user:

  con /srv/fscons
  uname jorge jorge =jorge
  uname sys +jorge

• exit with 'Ctl+\' q

authuser

* connect to the authserver

* launch the keyserver

* add the user password and other entries

auth/keyfs

auth/changeuser jorge

* answer the following questions: Password:

at least eight (8) characters

Confirm:

must be the same /!\ as above

assign Inferno/POP secret?:

y

make it the same as the plan 9 password?:

y

Expiration date (YYYYMMMDD or never)[return = never]:

just hit return

Post id:

an alias for the user

Users's full name:

..

Department:

..

Users's email address:

..

Sponsor's email address:

.. * this address receives copy of notifications when glenda's password is about to expire other email address:

.. don't ask, I sure don't know (yet?)

user profile

• connect as the new user to the cpu/fileserver
• run

  /sys/lib/newuser

Other Helpful Things

• ./RcProfile
  • This sets up a system wide 'profile' for the rc(1) shell, separating concerns from shell setup and user environment setup
• ./RcScripts
  • Several scripts which provide commands I find nice to have.
• ndb setup, to include Plan9 related systems:

cat > /lib/ndb/plan9 <<EOF
# /lib/ndb/plan9
# LEG20061122
#
# Plan9 related external systems

auth=sources.cs.bell-labs.com authdom=outside.plan9.bell-labs.com
auth=brd.9grid.de authdom=9grid.de
EOF

• then modify /lib/ndb/local to contain:

database=
        file=/lib/ndb/local
        file=/lib/ndb/common
        file=/lib/ndb/plan9
        file=/lib/ndb/auth

TODO

• delete a user
• setup ssh connections
• fossil+venti adm
• secstore
• explain network config, ntp config
• drawterm from Linux, Windows (?)
• 9fs to/from Linux
• nfs
• .?/CpuChangeHostowner