ref: 886a638fccaf754b9b30280e7b6b21923b206fa7
parent: 839028221769682cfd5a75f4db92a6d35bd312e1
author: kvik <kvik@a-b.xyz>
date: Fri Aug 14 14:01:29 EDT 2020
cpu-setup: draft
--- /dev/null
+++ b/cpu-setup.md
@@ -1,0 +1,181 @@
+# Setting up a networked 9front machine
+
+0. First off, we'll make our life bearable by setting up a
+ temporary cpu service listener. This will let us access the
+ new system with `rcpu(1)` or `drawterm(1)`, instead of having
+ to suffer some terrible VNC console or similar.
+
+ Make sure the machine has network access, then run the following:
+
+ echo 'key proto=dp9ik dom=9front user='$user' !password=BADBADDIE' >/mnt/factotum/ctl
+ aux/listen1 -t 'tcp!*!rcpu' /rc/bin/service/tcp17019
+
+1. Complete the standard installation using inst/start, then reboot
+ into a newly installed system.
+
+ The following steps assume the cwfs(4) was selected as the
+ file server, and that the basic networking works.
+
+2. Start with adding your own user to the file server, also add
+ it to some standard groups:
+
+ ; con -C /srv/cwfs.cmd
+ newuser kvik
+ newuser sys +kvik
+ newuser adm +kvik
+ newuser upas +kvik
+
+ Before proceeding, restart the machine and log in with the new
+ user, then run:
+
+ /sys/lib/newuser
+
+ This will set up your home directory.
+
+3. Setting up the FS listener
+
+ This step is OPTIONAL. If you don't plan to set up
+ TCP/TLS or PXE booting it is fine to skip it for now.
+
+ For `cwfs(4)` to start a network listener it must be told to
+ to so in the command line used to start it. This can be done
+ through the `plan9.ini`.
+
+ First we'll need to mount the `9fat` partition. If you aren't doing
+ this from the console, i.e. you've done step 0., then you'll have
+ to make sure you are mounting and modifying the target machine's
+ `plan9.ini`, and not the one belonging to your terminal. We can do
+ this by binding correct devices and being explicit with the `9fs`
+ command:
+
+ ; bind -b '#S' /dev
+ ; 9fs 9fat /dev/sdF0/9fat
+
+ You may now edit `/n/9fat/plan9.ini`.
+
+ Modify the `bootargs=` parameter as follows, or use the equivalent
+ `nobootprompt=` parameter to avoid the need for manual intervention
+ during the boot. The latter is highly recommended.
+
+ nobootprompt=local!/dev/sdF0/fscache -a tcp!*!564
+
+ This tells `cwfs(4)` to start a listener on port 564.
+
+ By default the file server doesn't require authentication, this
+ is so that local mounting can work without an auth server. However,
+ with the previous step we've exposed the file server to the network
+ which means anyone could mount it just by guessing an existing user.
+ To prevent this we'll tell the file server to authenticate remote
+ clients. This is done on the file server console by toggling the
+ `noauth` command. Make sure you get `auth enabled` message.
+
+ ; con -C /srv/cwfs.cmd
+ noauth
+ auth enabled
+
+4. Setting up the CPU listener
+
+ For CPU listener to get started it is enough to set the `service=`
+ boot parameter in `plan9.ini`:
+
+ service=cpu
+
+5. Setting up hands-free booting
+
+ In step 3. we've set up the `nobootprompt=` parameter, which makes
+ sure the root file system is mounted automatically at boot.
+ In this step we'll set up hostowner credential, the user name,
+ avoiding the need for manual intervention at the system console.
+
+ The auth credentials must be stored in the system NVRAM, which
+ is usually a small disk partition on the PC systems. We can
+ write to it with the help of the `auth/wrkey(8)` utility.
+
+ **NOTE** make very sure to enter correct information when prompted.
+ It is very common for people to mistype their password, or specify
+ the wrong authentication domain, or even username, which will cause
+ very hard to diagnose problems later on. The same information will
+ be asked for later when creating an auth user and configuring the
+ authentication server.
+
+ **NOTE 2** if you have followed the step 0. then it is best to
+ explicitly specify the `nvram` partition that you want to write to.
+ On PC some automatic process is used to find a suitable partition.
+ It is very likely that this process will guess wrong. Use the
+ `nvram=` environment variable to select the correct partition:
+
+ ; nvram=/dev/sdF0/nvram auth/wrkey
+ bad nvram des key
+ bad authentication id
+ bad authentication domain
+ authid: kvik
+ authdom: a-b.xyz
+ secstore key: <press enter to skip>
+ password: <type the password you wanna use>
+
+6. Setting up the AUTH server
+
+ We are almost done and ready to reboot, but almost nothing we set
+ up above will work before we set up an authentication server
+ which will authenticate us — the remote client — before letting'
+ us connect.
+
+ First we'll have to make sure that the authentication server
+ process starts during boot. This is done automatically by the
+ CPU machine's bootup procedure if it learns that it is intended
+ to be the authentication server. We tell it so by adding an
+ entry in the system network database which associates the
+ machine, the auth server, with an authentication domain that
+ it will serve.
+
+ Add the following entry on a line of its own in the file
+ `/lib/ndb/local`, replacing the domain with some domain or string
+ of your own:
+
+ auth=dum authdom=a-b.xyz
+
+ This associates the machine named `dum` with the authentication
+ domain `a-b.xyz`. Remember that this was the same authdom: that we
+ stored in the machine's nvram with `auth/wrkey`.
+
+ **NOTE** this entry is independent from everything else in this
+ file. Do not add it to either the `ipnet=` entry, or the `sys=`
+ line.
+
+ On the next reboot the machine `dum` will figure out it's supposed
+ to be an authentication server and start the services it needs
+ to act as one.
+
+ Now we can add users to the auth server. For this
+ we'll need to start up a temporary `keyfs(4)`, then use the
+ `auth/changeuser(8)` command to add the users:
+
+ ; auth/keyfs
+ ; auth/changeuser kvik
+ Password: <same as what's in nvram>
+ Confirm password:
+ assign new Inferno/POP secret? [y/n]: n
+ Expiration date (YYYYMMDD or never)[never]:
+ Post id:
+ User's full name:
+ Department #:
+ User's email address: kvik@a-b.xyz
+ Sponsor's email address:
+ user kvik installed for Plan 9
+
+ The last step involves letting our new user "speak for" other users.
+ This is a neccessary step if the hostowner of the machine
+ running the auth server is someone other than `glenda`, which
+ is the case for the setup we performed above.
+
+ Simply add the following entry to the file `/lib/ndb/auth`:
+
+ hostid=kvik
+ uid=!sys uid=!adm uid=*
+
+7. Reboot
+
+ fshalt -r
+
+ After reboot the machine should let you connect to it using
+ `drawterm` or `rcpu`.