shithub: docs.9front.org

Download patch

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`.