ref: b516c5e83b0a2c5ed8eb132d117197509cb6f8a2
parent: 3a122db65db2b610ed73d41695606a12f2c0ceba
author: kestrel <Ii8Aikie@proton.me>
date: Tue Jun 11 19:25:15 EDT 2024
cpu-setup: restructuring for minor corrections and ease of reading
--- a/cpu-setup.md
+++ b/cpu-setup.md
@@ -1,125 +1,145 @@
-# Setting up a networked 9front machine
+# Setting up a cpu server
-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.
+**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.
- Make sure the machine has network access, then run the following:
+## 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.
- echo 'key proto=dp9ik dom=9front user='$user' !password=BADBADDIE' >/mnt/factotum/ctl
- aux/listen1 -t 'tcp!*!rcpu' /rc/bin/service/tcp17019
+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`.
-2. Complete the standard installation using inst/start, then reboot
- into a newly installed system.
+Once the machine has network access, we can set up a temporary cpu service with
- The following steps assume the cwfs(4) was selected as the
- file server, and that the basic networking works.
+ ; echo 'key proto=dp9ik dom=9front user='$user' !password=BADBADDIE' >/mnt/factotum/ctl
+ ; aux/listen1 -t 'tcp!*!rcpu' /rc/bin/service/tcp17019
-3. Start with adding your own user to the file server, also add
- it to some standard groups:
+You can now connect to the machine using `drawterm -h <ip address> -u glenda`
+## 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
- Before proceeding, restart the machine and log in with the new
- user, then run:
+Then, issue the following commands to create a new user,
+and add it to common groups.
- /sys/lib/newuser
+ newuser alice
+ newuser sys +alice
+ newuser adm +alice
+ newuser upas +alice
- This will set up your home directory.
-
-4. Setting up the CPU listener
+Leave the console by pressing `Ctrl-\` and pressing enter, then q and enter.
- For CPU listener to get started at boot time it is enough to set
- the `service=` parameter in `plan9.ini`:
+- 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.
+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
-5. Setting up hands-free booting
+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
- 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.
+ ; 9fs 9fat
+ ; acme /n/9fat/plan9.ini
- 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/sdF0/fscache
- # change to...
- nobootprompt=local!/dev/sdF0/fscache
+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.
- 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.
+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.
- **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.
+**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 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:
+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*/`
; nvram=/dev/sdF0/nvram auth/wrkey
bad nvram des key
bad authentication id
bad authentication domain
- authid: kvik
- authdom: a-b.xyz
+ authid: alice
+ authdom: plan9.local
secstore key: <press enter to skip>
password: <type your password>
confirm pasword: <retype your password>
+ enable legacy p9sk1[no]:
-6. Setting up the AUTH server
+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.
- We are almost done and ready to reboot, but almost nothing set
- up above will work before an authentication server is running.
+**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.
- 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.
+## Setting up the auth server
+An authentication server needs to be set up to allow for users to log in.
- 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:
+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.
- auth=dum authdom=a-b.xyz
+ ipnet=plan9.local ip=192.168.0.0 ipmask=255.255.255.0
+ auth=nodename authdom=plan9.local
- 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`.
+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.
- **NOTE** this entry is independent from everything else in this
- file. Do not add it to either the `ipnet=` entry, or the `sys=`
- line.
+### 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:
- 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 kvik
+ ; auth/changeuser alice
Password: <same as what's in nvram>
Confirm password:
assign new Inferno/POP secret? [y/n]: n
@@ -127,23 +147,43 @@
Post id:
User's full name:
Department #:
- User's email address: kvik@a-b.xyz
+ User's email address:
Sponsor's email address:
- user kvik installed for Plan 9
+ user alice installed for Plan 9
- 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.
+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.
- Simply add the following entry to the file `/lib/ndb/auth`:
+Add the following entry to the file `/lib/ndb/auth`:
- hostid=kvik
+ hostid=alice
uid=!sys uid=!adm uid=*
-7. Reboot
+## 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:
+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 automagically and
- let you connect to it using `drawterm` or `rcpu`.
+After reboot, the machine should bring itself up without user interaction
+and allow you to connect to it using `drawterm` or `rcpu`.