DRAFT (version 0.2)

The Plan 9 Cpu/Auth Server Installation and Basic Setup Howto

Purpose:

The purpose of 'The Plan 9 Cpu/Auth Server Installation and Basic Setup Howto' is to walk a user through the configuration of a Plan 9 combined cpu/auth server in a straight forward, quick, and linear fashion.

Very little explanation is provided regarding each step in the process. The goal is to get you into a basic usable Plan 9 environment in the quickest manner possible, and to instill confidence that all the necessary and important configuration elements have been satisfied.

Assumptions:

The bulk of this howto focuses on what to do immediately after completing a standard Plan 9 terminal installation, and additionally requires that you will be able to perform basic editing and user interface operations in a Plan 9 gui environment.

Parts 0 and 1 of this document will direct you to the appropriate resources necessary to fulfill these two requirements.

Conventions:

Throughout the howto you will come accross certain commands and text edits which require information regarding the specific details related to your system and environment. These variables will be shown in brackets using lowercase characters. Whenever you see these in the text, replace them with the correct value as appropriate.

The variables contained in this text are as follows:

<systemname>	- Choose a name you want as an identifier for your system. (examples: 'darkstar', 'authsrv1', 'skippy')
<hd>	- The disk which your Plan 9 has been installed onto, commonly 'sdC0'. (examples: 'sdC0', 'sdC1', 'sdE0')
<hostip>	- The ip address reserved for your server. (example: '192.168.0.2')
<mac>	- The 12 digit hexadecimal mac address assigned to your ethernet card. (example: '050c411c715d')
<dnsip>	- The ip address of the dns server used on your network. (example: '192.168.0.1')
<gatewayip>	- The ip address of the network gateway used by your server. (example: '192.168.0.1')
<authdomain>	- A descriptive token assigned as an identifier for your network's authentication domain. (example: 'auth1', '9grid', 'your.domain.net')
<hostowner>	- The identifier choosen for the machine's hostowner user. Commonly 'bootes'. (examples: 'bootes', 'sysop', 'jdoe')
<hostownerpwd>	- The password assigned to the hostowner user. (example: 'secret')
<machinekey>	- A secret key assigned to the machine. (example: 'secret')
<secstorekey>	- The hostowner's sectore password. (example: 'secret')
<timezone>	- A text string describing your terminal's geographical region. (examples: 'US_Arizona', 'Canada_Mountain', 'GMT')

Part 0, Preparation:

Step 0] Introduction to the Plan 9 Operating System:

if you're new to Plan 9, read sections 1 through 3 of 'A Plan 9 Newbie's Guide' (http://www.quanstro.net/newbie-guide.pdf)

fully review this howto before starting

Part 1, Installation:

Step 0] Install Plan 9:

refer to the Plan 9 Installation Howto (not yet available - simply follow all defaults presented by the install script)

note: be sure to choose 'fossil' for configfs (i.e. no venti)

Part 2, Basic Setup:

note: It should take approximately 20 to 30 minutes to complete the configuration process

note: It is absolutely crucial that you carefully review your work in each step in order to avoid typos and errors, which may easily introduce problems that will be difficult and annoying to identify and correct later

Step 0] Boot into freshly installed Plan 9 terminal:

select local root and login as user glenda:

root is from (tcp, local)[local!#/sdC0/fossil]: <ENTER>
user[none]: glenda <ENTER>

read through the presented Rio and Acme introductions, then delete all rio windows

draw a new rio window, this will be used throughout the rest of the howto

note: it is suggested that you enable scrolling on your rio window (middle-click, select scroll)

Step 1] Assign user glenda to group adm:

connect to the fossilcons server, execute:

term% con -l /srv/fscons

issue command at prompt:

prompt: uname adm +glenda <ENTER>
<CTRL>-\
>>> q <ENTER>

Step 2] Set the timezone:

list available timezones, execute:

term% lc /adm/timezone

execute:

term% cp /adm/timezone/<timezone> /adm/timezone/local

Step 3] Prepare local rc script directory:

execute:

term% mv /cfg/example /cfg/<systemname>

Step 4] Enable dma on disk(s) and configure network interface:

edit /cfg/<systemname>/cpurc, append:

dmaon

ip/ipconfig

note: the above assumes a dhcp server is in use on your network;
if this is not the case, replace the ip/ipconfig line with:

ip/ipconfig -g <gatewayip> ether /net/ether0 <hostip> <subnetmask>

Step 5] Enable authentication services:

execute:

term% mv /rc/bin/service.auth/authsrv.tcp567 /rc/bin/service.auth/tcp567

create /cfg/<systemname>/cpustart, insert:

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

Step 6] Enable keyfs and cron:

edit /rc/bin/cpurc, locate and uncomment the following two lines:

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

Step 7] Configure basic network database settings:

get the ethernet card's mac address, execute:

term% cat /net/ether0/addr; echo

note: you may want to snarf the output from the above command

edit /lib/ndb/local, append:

ip=<hostip> sys=<systemname> ether=<mac>
   authdom=<authdomain> 
   auth=<systemname> 
   cpu=<systemname> 
   fs=<systemname> 
   dns=<dnsip>
   ipgw=<gatewayip>

confirm changes, execute:

term% ndb/query sys <systemname>

note: the output from the above command should show the expected values;
if this is not the case, re-check /lib/ndb/local for errors

Step 8] Compile and install a cpu kernel:

execute:

term% cd /sys/src/9/pc
term% mk 'CONF=pccpuf'

note: the above command will take a few moments to complete and will generate quite a bit of output to the window

execute:

term% 9fat:
term% cp 9pccpuf /n/9fat/

Step 9] Configure plan9.ini:

edit /n/9fat/plan9.ini, prepend:

[menu]
menuitem=cpu, Plan 9 CPU Kernel
menuitem=terminal, Plan 9 Terminal Kernel
menudefault=cpu, 10

[cpu]
bootfile=<hd>!9fat!9pccpuf

[terminal]
bootfile=<hd>!9fat!9pcf

[common]
nobootprompt=local!#S/<hd>/fossil

warning: make sure to remove the pre-existing bootfile=<hd>!9fat!9pcf entry from the top of this file;
additionally, ensure that all remaining entries beneath the [common] tag form a single contiguous block

warning: unless you compiled your cpu kernel with extra drivers, then you will have limited choices available for your monitor= and vgasize= entries (vesa won't be available, for instance)

Step 10] Prepare nvram and provide a password for this machine:

invalidate the current nvram contents, execute:

term% echo garbage >/dev/<hd>/nvram

execute:

term% auth/keyfs

follow prompts:

bad nvram key
bad authentication id
bad authentication domain
can't read /dev/key, please enter machine key
Password: <machinekey> <ENTER>
Confirm password: <machinekey> <ENTER>
0 keys read

Step 11] Create and configure the hostowner:

connect to the fossilcons server, execute:

term% con -l /srv/fscons

note: you may need to press <ENTER> a couple times before getting a prompt

issue commands at prompts:

prompt: uname <hostowner> <hostowner> <ENTER>
prompt: uname sys +<hostowner> <ENTER>
prompt: uname adm +<hostowner> <ENTER>
prompt: fsys main <ENTER>
main: create /active/cron/<hostowner> <hostowner> <hostowner> d775 <ENTER>
main: create /active/sys/log/cron <hostowner> <hostowner> a664 <ENTER>
<CTRL>-\
>>> q <ENTER>

edit /lib/ndb/auth, append:

hostid=<hostowner>
       uid=!sys uid=!adm uid=*

Step 12] Set hostowner password:

execute:

term% auth/changeuser <hostowner>

follow prompts:

Password: <hostownerpwd> <ENTER>
Confirm password: <hostownerpwd> <ENTER>
assign Inferno/POP secret? (y/n) y <ENTER>
make it the same as the plan 9 password? (y/n) y <ENTER>
Expiration date (YYYYMMDD or never)[return = never]: <ENTER>
1 keys read
Post id: <ENTER>
User's full name: <ENTER>
Department #: <ENTER>
User's email address: <ENTER>
Sponsor's email address: <ENTER>
user <hostowner> installed for Plan 9

note: it is important that you remember the <hostownerpwd> supplied here at the Password: prompt;
it will need to be accurately entered again during Step 14

Step 13] Shutdown and reboot:

execute:

term% fshalt

note: the above command may take a few moments to complete;
wait until you see the output: done halting

reboot the machine

Step 14] Initial login as hostowner:

select the new cpu kernel at prompt:

Plan 9 Startup Menu:
====================
   1. Plan 9 CPU Kernel
   2. Plan 9 Terminal Kernel
Selection[default==1 (10s timeout)]: 1 <ENTER>

create hostowner nvram key, follow prompts:

bad nvram key
bad authentication id
bad authentication domain
authid: <hostowner> <ENTER>
authdom: <authdomain> <ENTER>
secstore key: <secstorekey> <ENTER>
password: <hostownerpwd> <ENTER>

warning: be particularly careful when entering the <hostownerpwd> at the password: prompt;
failing to supply a matching password as entered at Step 12 will make it necessary to repeat Step 10

Step 15] Verify configuration:

scan for any obvious errors or warnings which may have occurred during bootup, execute:

systemname# cat /dev/kmesg

confirm that basic networking is functional, execute:

systemname# ip/ping -n 3 <systemname>
systemname# ip/ping -n 3 plan9.bell-labs.com

Step 16] Test remote access:

note: carry out these tasks on a different machine, presumably a standard desktop os

download and install drawterm for your platform: http://swtch.com/drawterm/

run: drawterm -a <systemname> -c <systemname> -u <hostowner>

at the drawterm login prompt, enter <hostownerpwd> to attach to your cpu server

setup initial environment for hostowner, execute:

systemname# /sys/lib/newuser

you should be presented with the familiar grey screen of an empty rio session

note: it is only necessary to execute /sys/lib/newuser once for any new user

note: your attempt to login via drawterm may error with: ?password mismatch with auth server
if this is the case, re-running the auth/changeuser command as per Step 12 may solve the issue

Step 17] Congratulations:

you should now hopefully have a functional Plan 9 standalone cpu/auth server!
refer to the Common Administrative Tasks document for further instruction

note: if you ran into any issues, please review the Commonly Encountered Problems document

TODO:

* complete the 'Commonly Encountered Problems' document

* complete the 'Common Administrative Tasks' document (when this gets lengthy enough, it will likely be divided into separate independent howto's)