ref: 5f97fe3e3508a84481376c0e7470a19c7596e5e3
parent: 493b3859c1165a61e49e316af3502031a33d4e87
author: grobe0ba <grobe0ba@tcp80.org>
date: Sat Jun 15 10:19:25 EDT 2024
Revert "cpu-setup: restructuring for minor corrections and ease of reading" This reverts commit b516c5e83b0a2c5ed8eb132d117197509cb6f8a2.
--- a/cpu-setup.md
+++ b/cpu-setup.md
@@ -1,145 +1,125 @@
-# Setting up a cpu server
+# Setting up a networked 9front machine
-**Notation**: Some commands in this document begin with a semicolon `; `.
-This is to indicate the prompt input, to distinguish between rc commands,
-and following user interaction with running programs.
+1. 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.
-## Before installation
-It might be beneficial to set up a temporary cpu service, as this will let you
-access the installer from a client software such as
-[`rcpu(1)`](http://man.9front.org/1/rcpu), [`drawterm(1)`](http://drawterm.9front.org/)
-or [tlsclient](https://git.sr.ht/~moody/tlsclient).
-This allows copy-and-pasting of commands.
-`rcpu` is the Plan 9 equivalent of `ssh` or `telnet`,
-which allows you to remotely open an `rc` shell session;
-and `drawterm` is akin to a remote desktop.
-rcpu is only available on 9front.
+ Make sure the machine has network access, then run the following:
-If the machine does not have network access, it can be set up using
-`ip/ipconfig ether /net/ether0`, which will configure the network using DHCP.
-Verify the machine has network using `ip/ping`.
-The IP address of the machine can be printed by `cat /net/ndb`.
+ echo 'key proto=dp9ik dom=9front user='$user' !password=BADBADDIE' >/mnt/factotum/ctl
+ aux/listen1 -t 'tcp!*!rcpu' /rc/bin/service/tcp17019
-Once the machine has network access, we can set up a temporary cpu service with
+2. Complete the standard installation using inst/start, then reboot
+ into a newly installed system.
- ; echo 'key proto=dp9ik dom=9front user='$user' !password=BADBADDIE' >/mnt/factotum/ctl
- ; aux/listen1 -t 'tcp!*!rcpu' /rc/bin/service/tcp17019
+ The following steps assume the cwfs(4) was selected as the
+ file server, and that the basic networking works.
-You can now connect to the machine using `drawterm -h <ip address> -u glenda`
+3. Start with adding your own user to the file server, also add
+ it to some standard groups:
-## Install to disk
-Install 9front onto disk with `inst/start`, then reboot into the newly installed system.
-Installation instructions are available at [fqa4](fqa.9front.org/fqa4.html).
-
-The following steps are written assuming cwfs(4) was selected as the file server,
-and the machine has basic networking.
-
-## Create new user
-A new user can be added to the fileserver by sending
-the following commands to /srv/cwfs.cmd.
-
-First, open a console into `/srv/cwfs.cmd`.
-
; con -C /srv/cwfs.cmd
+ newuser kvik
+ newuser sys +kvik
+ newuser adm +kvik
+ newuser upas +kvik
-Then, issue the following commands to create a new user,
-and add it to common groups.
+ Before proceeding, restart the machine and log in with the new
+ user, then run:
- newuser alice
- newuser sys +alice
- newuser adm +alice
- newuser upas +alice
+ /sys/lib/newuser
-Leave the console by pressing `Ctrl-\` and pressing enter, then q and enter.
+ This will set up your home directory.
+
+4. Setting up the CPU listener
-- Most of the filesystem is owned by `sys`,
-being a member of this group grants permissions to manage /sys/src and other resources.
-- `adm` group allows access to /adm, which stores auth server keys, timezones,
-and the users file.
-- `upas` is the group for mail server. it allows delivery of mail to your mailbox.
+ For CPU listener to get started at boot time it is enough to set
+ the `service=` parameter in `plan9.ini`:
-Now, you can reboot the machine with `fshalt -r` in order to change user, then run
-
- ; /sys/lib/newuser
-
-as the new user to set up the home directory with default settings.
-
-To complete the following steps, you should reboot again and log in as *glenda*.
-
-## Setting up the CPU service
-To start the cpu service at boot, edit `plan9.ini`
-and append the following line to it:
-
service=cpu
-This kernel parameter starts the machine as a cpu server
-rather than a terminal/workstation.
-
-`plan9.ini` is at the 9fat partition, and can be accessed using
+5. Setting up hands-free booting
- ; 9fs 9fat
- ; acme /n/9fat/plan9.ini
+ While booting the system will prompt for several parameters
+ like the disk partition to mount, user name and password, and
+ possibly some others.
+ This is an issue for CPU servers which usually boot in the dark,
+ with no one present at the console to confirm the defaults.
+ We want to specify and confirm these parameters up front instead.
----
+ First, we want to skip the `bootargs` prompt asking us to select
+ the partition to boot from. This is done by changing the `plan9.ini`
+ key `bootargs=` to `nobootprompt=`; the value stays the same.
-Next we'll store the hostowner authentication credentials.
-These must be stored in the NVRAM, a special partition which stores data for factotum.
-We can write to it with the `auth/wrkey(8)` command.
+ bootargs=local!/dev/sdF0/fscache
+ # change to...
+ nobootprompt=local!/dev/sdF0/fscache
-If you are netbooting, this information allows the cpu server to mount a remote
-filesystem without manual interaction. It also serves as a fallback,
-if for any reason the auth server is non-functioning, you can still login using
-the auth information stored in the factotum from nvram.
+ Next we'll store the hostowner authentication credentials. These
+ must be stored in the so-called NVRAM, which is just a small disk
+ partition on PC systems. We can write to it with the `auth/wrkey(8)`
+ command.
-**Note**: it is important to enter the following information correctly.
-The information you will provide here will be required in subsequent steps when
-creating an auth user and configuring the auth server.
+ **NOTE** Make very sure to enter correct information when prompted.
+ It is very common for people to mistype their password, or specify
+ a 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.
-It is good practice to explicitly specify the nvram partition using
-the environment variable `nvram` when calling `auth/wrkey`.
-The available partitions can be listed by running `ls /dev/sd*/`
+ **NOTE 2** If you have followed the step 1. 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: alice
- authdom: plan9.local
+ authid: kvik
+ authdom: a-b.xyz
secstore key: <press enter to skip>
password: <type your password>
confirm pasword: <retype your password>
- enable legacy p9sk1[no]:
-The secstore key allows the cpu server to load additional information such as
-ssh keys or tls secrets into factorum from `secstored`, which is only needed if
- one plans to use secstored. It can be safely skipped here.
+6. Setting up the AUTH server
-**Note**: it is discouraged to enable the legacy p9sk1 protocol.
-It is used to interact with non-9front Plan 9 machines,
-and is considered vulnerable for using DES encryption.
+ We are almost done and ready to reboot, but almost nothing set
+ up above will work before an authentication server is running.
-## Setting up the auth server
-An authentication server needs to be set up to allow for users to log in.
+ 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 supposed
+ 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.
-In order for the machine to run authsrv(6), we must define it as an auth server
-in the ndb. A typical auth server is intended to be used by a cluster of machines
-in a particular subnet.
-Adding the following to `/lib/ndb/local` defines that `nodename` be used as the
-auth server for every machine in the 192.168.0.0/24 subnet.
+ 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:
- ipnet=plan9.local ip=192.168.0.0 ipmask=255.255.255.0
- auth=nodename authdom=plan9.local
+ auth=dum authdom=a-b.xyz
-These names can be changed to your liking, however our auth domain has to be the
-same as the one stored in nvram by `auth/wrkey` in the preceeding step.
+ 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`.
-### Add users to auth server
-Now we can add users to the auth server.
-For this, we start a temporary `keyfs(4)`,
-then use the `auth/changeuser(8)` command to add users:
+ **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 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 start a temporary
+ `keyfs(4)`, then use `auth/changeuser(8)` command to add users:
+
; auth/keyfs
- ; auth/changeuser alice
+ ; auth/changeuser kvik
Password: <same as what's in nvram>
Confirm password:
assign new Inferno/POP secret? [y/n]: n
@@ -147,43 +127,23 @@
Post id:
User's full name:
Department #:
- User's email address:
+ User's email address: kvik@a-b.xyz
Sponsor's email address:
- user alice installed for Plan 9
+ user kvik installed for Plan 9
-The final step involves letting our new user "speak for" other users.
-This is neccessary if the hostowner of the machine running the auth server is
-someone other than `glenda`, which is the case here.
+ Final step involves letting our new user "speak for" other users.
+ This is neccessary if the hostowner of the machine
+ running the auth server is someone other than `glenda`, which
+ is the case here.
-Add the following entry to the file `/lib/ndb/auth`:
+ Simply add the following entry to the file `/lib/ndb/auth`:
- hostid=alice
+ hostid=kvik
uid=!sys uid=!adm uid=*
-## Hands-free booting (optional)
-By default, 9front will prompt for several parameters like the disk partition to mount,
-user name and password, and possibly some others.
-This is may be a problem for headless CPU servers
-with no one present at the console to confirm the defaults.
-These parameters can be supplied without user interaction with
-the following changes:
+7. Reboot
-First, we want to skip the `bootargs` prompt asking us to
-select the partition to boot from.
-This is done by changing the `plan9.ini` key `bootargs=` to `nobootprompt=`;
-the value stays the same.
-
- bootargs=local!/dev/sd..
- # change to...
- nobootprompt=local!/dev/sd..
-
-Finally, add the following line to change the default user
-
- user=alice
-
-## Reboot
-
fshalt -r
-After reboot, the machine should bring itself up without user interaction
-and allow you to connect to it using `drawterm` or `rcpu`.
+ After reboot the machine should bring itself up automagically and
+ let you connect to it using `drawterm` or `rcpu`.